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EDITOR'S NOTE 



DAVE JOHNSON 
FOR CAROLINE ROSE 


As I write this our esteemed Editor-in-Cheek is off on sabbatical, indulging in a little 
global gallivanting and some well deserved {and completely unstructured) hanging 
around. Thus it falls to me to write this editorial, making this only the second issue of 
develop that has had two pictures of me in it (trivia question: which was the other?), 
and also marking the first time (and hopefully the last time) my signature has been 
aired in public, (Yes, I know it’s illegible, and I confess: I never really learned to write 
cursive. So ids only a rough approximation. Even my printing is barely Legible. Thank 
goodness for keyboards.) 

Unaccustomed as I am to editorial speaking, I was having a hard time thinking of 
something to write about. Fortuitously, Apple’s Worldwide Developers Conference 
occurred just about the time 1 needed to settle on a topic, and as always the developers 
1 talked with at the conference brought up several issues about what we on the develop 
staff do and why we do it that way. 


One issue that came up is conveniently editorial in nature, We’re often applauded for 
the better-than-usual (at least for a technical journal) writing in our articles and 
columns. It’s quite true that in addition to trying to make sure everything in the 
magazine is correct, we also put a lot of effort into making it read well. This is great 
for you, the reader, but as with any way of doing things there’s a downside. In this 
case, it means more trouble and more work for those who generate the content of the 
journal. Occasionally an author thinks it’s a hassle, all that fussing over finding the 
right word or phrase, all that questioning and worrying over something that’s “off die 
topic 11 as far as they’re concerned. For others, of course, it’s a real blessing, having our 
highly trained team of crackerjack editors swarming over their work, nipping and 
nicking and polishing it until it’s snug and smooth and gleaming. While I naturally 
tend to side with the latter, everybody’s entitled to an opinion. 


Those of us here at develop believe that it’s absolutely worth it. It’s a truism about 
technical writing that if it’s done well no one notices it. That’s our goal, and always 
has been, and I think it’s a good and important one. If you have to read a sentence 
twice or three times to figure out what it means, or if you have to backtrack a page to 
make sense of something you just read, or if you can’t find a constant in Inside Macintosh 
because it’s spelled wrong in the article, then the writing will be noticed, because it’s 
getting in your way. That’s something we’re proud to avoid more often than not, even 
though it takes longer, and even though it’s a lot more work. We hope you agree. 

So that’s my editorial. An easy out, some might say, simply restating our editorial 
philosophy rather than coming up with new thoughts. But it’s something that’s often 
lost in all the noise, and I think it’s good — both for us and for you — to be reminded 
once in a while why it is we do what we do. 

Dave Johnson 

Editorial Pretender 


DAVE JOHNSON [dkj@apple.com] and his 
wiFe Lisa have a liny but thriving mask-making 
business in San Francisco, selling masks for □ 
one-month period each year around Halloween, 
In 1994 they had sales of $344 and gross profits 
were $ 159. (There was a write-down of $ 188 


that year for retooling, resulting in a net loss of 
$29.) In 1995 they had totaJ profits of $287 on 
sales of $330. If this explosive profit growth keeps 
up, this small garage business could, in time, be 
worth literally hundreds of millions of dollars. 
Dave is rubbing his hands in anticipation,* 
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LETTERS 


NURB CURVES TYPO 

Pm an M.S. student in the Department 
of Industrial Engineering at Bogazici 
University, Istanbul, Turkey, My thesis is 
about pattern recognition using implicit 
polynomials in CAD applications. While 
I was surfing the Internet, I found the 
article U NURB Curves: A Guide for the 
Uninitiated” in develop Issue 25 and read 
it, IPs a very good resource for those (like 
me) with minimal knowledge of NURB 
curves and representations, and I liked it 
a lot. 

But in Figure 20 there’s a mistake, I 
think. Control point B 2 has coordinates 
{2, 0, 0}, but I believe the last index (zz?) 
should be 1. Is that right? 

— Ugur Murat Erdem 

lh\ tn fact you’ve found a typographical 
error in the figure you mention: B 2 should 
be {2 y G y 1}. We had a very good editor and 
several reviewers, but none of them caught 
this , I hope it doesn V mislead anyone too 
much. Thanks far pointing it out. 

— Philip Schneider 

TECHNICAL Q&A: WHERE? 

In the Issue 25 Macintosh Q&A, you 
explain a new method for embedding GX 
pictures into QuickDraw PICT files. It 
says chat we can find sample code in the 
Macintosh Technical Q&A “Embedding 
a GX Picture into a PICT” (GX 07), 
Unfortunately, I haven’t found this file 
on any developer CD 1 have. Could you 
please help me locate this information? 

— Michel Ren on 

That Q&A can be found on the Web at 
h tip://dev. info, apple, com/techqa/qdgx/ 


gx07.html In general, the Web site http:// 
dev . infoMppk.com/techqa/Maimbirni has 
the latest and greatest Macintosh Technical 
Q&As. They sometimes take a while to find 
their way to the CDs , and that was the case 
her e. That Q&A is now available on the 
CDs as well Sorry for any incon venience. 

— Dave Johnson 

TIME-SAVING TIPS 

I really enjoyed Bo3b Johnson’s Veteran 
Neophyte column in Issue 25 about 
ways to avoid wasting time. After 
programming the Mac for 10 years, Pm 
finally learning many of the things he 
talked about. It’s funny looking back at 
all the mistakes Pve made while thinking 
I was so smart. 

I worked at Berkeley Systems on After 
Dark, One of the first things I did was 
write the Warp (or star field) screen saver, 
I came up with a really cool assembly 
routine that, given an x and^, would 
draw the pixel on any monitor at any bit 
depth. It was a complicated routine 
(remember, Pm very smart) that used 
lots of shifts, multiplies, and divides. 
Even though I commented it, I still had 
to sit down and work through it each 
time I needed to make a change. Finally 
a coworker asked why I didn’t just write 
a separate routine for each hit depth, I 
scoffed and said my routine was really 
cool. Needless to say, I rewrote it into 
separate routines; it was really easy, and 
is easy to maintain and change as well. 

These days, instead of banging my head 
trying to come up with a "smart” w r ay 
to do things, I just code in the most 
straightforward way I know how. Pm 
finding that I have better things to do 
than screw around with a triply linked 
list that looked good in Dr. Dobbs but 


TELL US WHAT YOU THINK (PLEASE) 

We welcome your letters to the editor, especially 
regarding articles published in develop. Write to 
Caroline Rose at crose@opple.com or, if technical 
devefop-re la ted questions, to Dave Johnson at 
dkj@apple.com. All letters should include your 


name and company name as well as your address 
and phone number. Letters may be excerpted or 
edited for clarity (or to make them say what we 
wish they did). Address subscription-related 
queries to order.adc@applelink.apple.com. 6 


LETTERS 3 





isn’t really appropriate for my problem. 

I hate reliance on C-isms that aren’t 
obvious: if you have to pull out the 
ANSI C book to figure it out, it isn’t 
good code. 

By the way, another good book Is The 
Psychology of Computer Programming by 
Gerald M. Weinberg, It was written in 
1971 but has some very interesting views 
on programming and programmers, 

— Bruce Burkhalter 

I’m not a windsurfer, but I am a Mac 
developer, so I read Bu3b Johnson’s 
column in Issue 25 w T ith great interest. 
My boss (Markus Fest, the programmer 
of Toast CD-ROiM Pro) told me it was a 
Pfliehtlektiire (something you just gotta 
read). He was right. 

There’s a book that should have been in 
your Recommended Reading section: 
Code Complete by Steve McConnell 
(Microsoft Press, 1993). It’s worth 
checking out. Enjoy! 

— Honan Dejako 


It's amusing to look back and see bow we 
learned the things we did, and how they've 
helped or hindered us. That introspection is 
actually what spawned the column: l realized 
that maybe others could avoid those mistakes 
if they read about them in advance , 

To this day I run into arguments about using 
the full u power' of C/C++. / hate to see 
people writing code just to use some feature 
of C++ like operator overloading. If they can 
redirect that creative energy to figuring out 
a better algorithm , its a total win. 

I think restrictions am actually be liberating, 
by freeing you from having to think about 
everything. If the brace style in code were 
enforced , how many homy of wasted brain 
time would we get back? Having the 
meaningless stuff like brace style fixed in 
stone makes it easier to apply cleverness to 
the things that matter^ like the quality of the 
software. 

Ami Florian: thanks. Pve never been called 
a Pjlichtkkture before , but / kin da like it. 

— Bosh Johnson 
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well as on the Internet.) For more information about how to order printed back 
issues (and where to find them online), sec die inside front cover o! this issue. 
Supplies arc limited. Please allow 4 to 6 weeks for delively. 
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The Speech Recognition Manager Revealed 


As any Star Trek fan knows, the computer of the future will talk and 
listen. Macintosh computers have already been talking for a decade , 
using speech synthesis technologies such as MacinTalk or the Speech 
Synthesis Manager. Now any Power Macintosh application can use 
Apple’s new Speech Recognition Manager to recognize and respond to 
spoken commands as well. We’ll show you how easy it is to add speech 
recognition to your application. 



MATT PALLAKOFF AND 
ARLO REEVES 


Speech recognition technology has improved significantly in the last few years. It 
may still be a long while before you 11 be able to carry cm arbitrary conversations with 
your computer. But if you understand the capabilities and limitations of the new 
Speech Recognition Manager, you 11 find it easy to create speech recognition 
applications that are fast, accurate, anti robust* 

Midi code samples from a simple speech recognition application, SRSample, this 
article shows you how to quickly get started using the Speech Recognition Manager. 
You’ll also get some rips on how to make your application’s use of speech recognition 
compelling, intuitive, and reliable. For everything you need in order to use the 
Speech Recognition Manager in your application (including SRSample and detailed 
documentation), see this issue’s CD or Apple’s speech technology Web site at 
http://w ww spe ech .apple, con i, 

WHAT THE SPEECH RECOGNITION MANAGER CAN AND 
CANNOT DO 


The Speech Recognition Manager consists of an API and a recognition engine. 
Under System 7.5, these are packaged together in version 1.5 or later of the Speech 
Recognition extension. (This packaging may change in future OS versions.) 


The Speech Recognition Manager runs only on Power Macintosh computers with 
16-bit sound input. Speech recognition is simply too computation-intensive to run 


MATT PALLAKOFF (mattp@appte.com), Apple's 
Speech Recognition engineering manager, likes 
to talk to inanimate objects. He has spent the last 
several years helping Apple's speech group putt 
speech recognition technology kicking and 
screaming over a threshold of usability that (as of 
PlainTalk 1.4) finally allows Power Macintosh 
users to leave speech recognition on and use it in 
simple ways every day He denies ever having 
worked in the field of Artificial Intelligence,* 


ARLO REEVES (arlo@apple.com) has had a 
varied employment history that includes baby¬ 
sitting young Peregrine falcons in Yosemite, 
studying variable stars from Nantucket, and 
adding two-dimensional FFT capabilities to N1H 
Image. Lately he's been helping Mat! and the 
speech team at Apple bring the Speech 
Recognition Manager into existence. Arlo lives in 
Santa Cruz, Californio, where he enjoys spending 
his Free time out of doors with his friends. ° 
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well on most 680x0 systems. The installed base of Power Macs is growing by about 
five million a year, however, so plenty of machines — including the latest PowerPC™ 
processor-based PowerBooks — can run speech recognition. 

The current version of the Speech Recognition Manager has the following 
capabilities and limitations: 

* It's speaker independent, meaning that users don’t need to train it before 
they can use it. 

* It recognizes continuous speech, so users can speak naturally , without — 
pausing — between — words, 

* IPs designed for Nordi American adult speakers of English. IPs not localized 
yet, and in general it won’t work as well for children. 

* It supports comtnand-and-control recognition, not dictation. It works well 
when your application asks it to listen for at most a few r dozen phrases at a 
time; however, it can’t recognize arbitrary sentences and its accuracy 
decreases substantially if the number of utterances it’s asked to listen for 
grows too large. For example, it won’t accurately recognize one name out of 
a list of five thousand names. 

OVERVIEW OF THE SPEECH RECOGNITION MANAGER API 

To use the Speech Recognition Manager, you must first open a recognition system, 
which loads and initializes the recognition toolbox. You dien allocate a recognizer, 
which listens to a speech source for sound input. A recognizer might also display a 
feedback window that shows the user when to speak and what the recognizer thinks 
was said. 

do define the spoken utterances that the recognizer should listen for, you build a 
language model and pass it to the recognizer. A language model is a flexible netw ork 
of words and phrases that de fi nes a large number of possible utterances in a compact 
and efficient way. The Speech Recognition Manager lets your application rapidly 
change the active language model, so that at different times your application can listen 
for different things. 

After the recognizer Is told to start listening, it sends your application a recognition 
remit whenever it hears the user speak an utterance contained in the current language 
model. A recognition result contains the part of the language model that was 
recognized and is typically sent to your application via Apple events. (Alternatively, 
you can request notification using callbacks if you cannot support Apple events.) Your 
application then processes the recognition result to examine what the user said and 
responds appropriately. 

Figure 1 shows how the Speech Recognition Manager works. Note that the 
telephone speech source is not supported in version 1,5 of die Speech Recognition 
extension. 

SPEECH OBJECTS 

The recognition system, recognizer, speech source, language models, and recognition 
results are all objects belonging to classes derived from the SRSpeechObject class, 
in accordance with object-oriented design principles. These and other objects are 
arranged into the class hierarchy shown in Figure 2. The class hierarchy gives the 
Speech Recognition Manager API the flexibility of polymorphism. For example, you 
can call the routine SKKeleaseObject to dispose of any SRSpeechObject. 
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Figure 1 . How the Speech Recognition Manager works 


SRSpeechObject 



SRRecognitionResult 



Figure 2. The speech object class hierarchy 

The most important speech objects are as follows: 

* SRRecognitionSystem — An appl ication typically opens one of these at 
startup (by calling SROpen Recognition System) and closes it at shutdown 
(by calling SRCloseRecognmonSystem). Applications allocate other kinds 
of objects by calling routines like SRNewWord, which typically take the 
SRRecognitionSystem object as their first argument. 

* SRRecognizer — An application gets an SRRecognizer from an 
SRRecognitionSystem by calling SRNewRecognizen The SRRecognizer 
does the work of recognizing utterances and sending recognition results 
back to the application. It begins doing this whenever the application calls 
SRStartListening and stops whenever the application calls SRStopListening. 

* SRLanguageModel, SRPath, SRPhrase, SRWord — An application builds 
its language models from these object types, which are all subclasses of 
SRLanguageObject, (A phrase is a sequence of one or more words, and a path 
is a sequence of words, phrases, and language models.) A language model, in 
turn, describes what a user can say at any given moment For example, if an 
application displayed ten animals and wanted to allow the user to say any of 
the animals 3 names, it might build a language model containing ten phrases, 
each corresponding to an animal *s name. 
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* SRRecognitionResult — When an utterance is recognized, an 

SRRecognitionResult object is sent (using either an Apple event or a 
callback routine, whichever the application prefers) to the application that 
was listening for that utterance* The SRRecognitionResult object describes 
what was recognized. An application can then look at the result in several 
forms: as text, as SRWords and SRFhrases, or as an SRLanguageModel, 
which can assist in quickly interpreting the uttered phrase* 

Each class of speech object has a number of properties that define how the objects 
behave* For example, all descendants of SRLanguageObject have a kSRSpelling 
property that shows how they're spelled. Your application uses the SRSetProperty 
and SRGetProperty routines to set and get the various properties of each these 
objects. 

RELEASING OBJECT REFERENCES 

You create objects by calling routines like SRNewRecognizer and SRNew Word. 

When youVe finished using them, you dispose of them by calling SRReleaseObject. 
You can also acquire references to existing objects by calling routines like 
SRGetlndexedltem (for example, to get the second word in a phrase of several 
words). 

The Speech Recognition Manager maintains a reference count for each object. 

An objects reference count is incremented by SRNew*,, and SRGet,., calls, and is 
decremented by calls to SRReleaseObject An object gets disposed of only when 
its reference count is decremented to 0. Thus, to avoid memory leaks, your application 
must balance eveiy SRNew... or SRGet,*, call with a call to SRReleaseObject 

A SIMPLE SPEECH RECOGNITION EXAMPLE 

It’s easy to add simple speech recognition capabilities to your application* All you 
need to do is perform a small number of operations in sequence: 

1. Initialize speech recognition by determining whether a valid version of the 
Speech Recognition Manager is installed, opening an SRRecognitionSystem, 
allocating an SRRecognizer, and installing an Apple event handler to handle 
recognition result notifications. 

2. Build a language model that specifies the utterances your application is 
listening for* 

3. Set the recognizer’s active language model to the one you built and call 
SRStartListening to start listening and processing recognition result 
notifications* 

We'll describe each of these operations in more detail. 

INITIALIZING SPEECH RECOGNITION 

First, you must verify that a valid version of the Speech Recognition Manager is 
installed on the target machine* Listing I shows how to do this. Note that only 
versions 1.5 and later of the Speech Recognition Manager adhere to the API used in 
this article* 

Listing 2 shows how to open an SRRecognitionSystem, allocate an SRRecognizer, 
and install your Apple event handler. All of this happens when your application 
starts up. The Apple event handler HandleRecognitionDoneAE is showm later (in 
Listing 4). 
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Listing 1, Determining the Speech Recognition Manager version 

Boolean EasValidSpeechRecognitionVersion (void) 

{ 

GSErr status? 

long theVersion; 

Boolean validVersion = false; 

const unsigned long kMininiuinRequiredSRMVersion = 0x00000150; 

status = Gestalt{gestaltSpeechRecognitionVersion, atheVersion); 
if (Istatus) 

if (theVersion >= kMinimuinRequiredSRMVersion) 
validVersion = true; 

return validVersion; 

} 


Listing 2. Initializing the Speech Recognition Manager 
/* Our global variables */ 

SRRecognitionSystem gRecognitionSystem = NULL; 

SRRecognizer gRecognizer = NULL; 

SRLanguageModel gTopLanguageModel = NULL; 

AEEventHandlerUFF gAERoutineDescriptor = NULL; 

OSErr InitSpeechRecognition (void) 

{ 

OSErr status - kBadSRMVersion; 

/* Ensure that the Speech Recognition Manager is available* */ 
if (EasValidSpeechRecognitionVersion()) { 

/* Open the default recognition system* */ 

status = SROpenRecognitionSystemt&gRecognitionSystem, 

kSRDefaultRecognitionSystemlD); 

/* Use standard feedback window and listening modes. */ 
if (Istatus) { 

short feedbackNeeded - kSRHasFeedbackHasListenModes; 

s tatu s ~ S RSet Proper ty(gRe cognition System, 

kSRFeedbackAndListeningModes, eedbackNeeded, 
sizeof(feedbackNeeded)); 

J 

/* Create a new recognizer* */ 
if (lstatus) 

status = SRNewRecognizer(gRecognitionSystem, sgRecognizer, 

kS RDef aultSpe ec h S ourc e); 

/* Install our Apple event handler for recognition results. */ 
if (1 status) { 

status = memFullErr; 

(continued on next page) 








Listing 2, Initializing the Speech Recognition Manager (continued) 


} 


gAERoutineDescriptor = 

NewAEEventHandlerProc(HandleReeognitionDoneAE); 
if (gMRoutineDescriptor) 

status = MInstaXlEventHandXer(kAESpeechSuite, kAESpeechDone, 
gAERoutineDescriptori 0, false); 


return status; 

} 


Notice in Listing 2 how we call SRSetProperty to request Apple’s standard feedback 
and listening modes for the recognizer. To have a successful experience with speech 
recognition, users need good feedback indicating when the recognizer is ready for 
them to talk and what utterances the recognizer has recognized (for more on giving 
feedback, see “Speech Recognition Tips”). In addition, because of the recognizer’s 
tendency to misinterpret background conversation and noises as speech, it’s usually a 
good idea to let the user tell the recognizer when to listen by pressing a predefined 
key (the “push-to-talk” key). Your application can get all of this important behavior 
for free, simply by setting the kSRFeedbackAndListeningModes property. 

With Apple’s Speech control panel (which comes bundled on new Macintoshes and 
with system updates), users can tailor this behavior to suit their needs, choosing 
preferred feedback characters (that is, the cartoon faces displayed in the feedback 
window) and preferred push-to-talk keys. 

BUILDING A SIMPLE LANGUAGE MODEL 

Your application needs to build a language model -— gTopLanguageMode] in our 
sample code — that specifics what the recognizer is listening for. The routine in 
Listing 3 shows how your application can create a simple language model. (We’ll 
discuss fancier language models later in this article.) Even simple language models 
should avoid using phrases that sound similar to one another; just like a human 
listener, the recognizer may have a hard time distinguishing between similar- 
sounding phrases. 

A recognizer returns a special speech object, called the rejection word , if it hears an 
utterance but cannot recognize it. Listing 3 sets the reference constant of the top- 
level language model to a predefined value to be able to distinguish that model from 
the rejection word. 

Note in Listing 3 that we add the phrases “Hello,” “Goodbye,” and “What time is it?” 
to our gTopLanguageModel using the call SRAddText, a convenient shortcut for the 
sequence of calls SRNewPhrase, SRAddLanguageObject, and SRReleaseObject. 
SRAddText also sets the kSRRefCon property of each added phrase. We’ll use this 
reference constant when we examine the recognition result to help determine what 
was said. 


HANDLING RECOGNITION RESULT NOTIFICATIONS 

Now let’s look at how your application would process result notifications given this 
simple language model. 
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SPEECH RECOGNITION TIPS 

Speech recognition is a completely new input mode, and 
using it properly isn't always as straightforward as it 
might seem. While we don't yet have a complete set of 
human interface guidelines to guarantee a consistent and 
intuitive speech recognition user experience, there are a 
few simple rules that all speech recognition applications 
should Follow. 

GIVE FEEDBACK 

Your application must always provide feedback to let 
users know when they can speak, when their utterance 
has been recognized, and haw it was interpreted. The 
Feedback services in the Speech Recognition Manager 
perform this for you, using the standard feedback window 
shown in Figure 3. [The user's recognized utterances are 
shown in italics, and the displayed feedback is In plain 
text. The string under the feedback character's face 
indicates the push-lota Ik key.) All you need to do is set the 
kSRFeedbackAndLisfemngModes property os shown in 
Listing 2. 


X//// 

Goodbye 

1 <”*• 

c Jr 

Don't leave now! 

Tell me tt/e price ef Apple stock 

Apple stock is priced to move! 

w 

Esc 

Whet time le It ? 

It's time to use the Speech 

Recog ni ti o n Ma naqe r! 


Figure 3, Standard feedback window 

Your application should use this standard feedback 
behavior unless you have a very good reason to provide 
your own feedback and custom pusMo-talk options, 

[Fast action games that take over the entire screen and 
don't coll WaitNextEvent are examples of applications 
that wouldn't use the standard feedback-] Not only will 
users enjoy the beneFits of consistent behavior, but as 
Apple improves the feedback components, your speech 


recognition applications will automatically inherit this 
improved behavior without having to be recompiled, 

SHOW WHAT CAN BE SAID 

Successful speech recognition applications always let the 
user know what he or she can say. The way they achieve 
this depends on the application, but one good example is 
a Web browser that makes all visible hyperlinks speakable. 
This lets the user know what can be said while restricting 
the size of the language model to improve recognition 
accuracy. 

CONSTRAIN THE LANGUAGE MODEL 

The recognition technology currently used by the Speech 
Recognition Manager works best when it's listening for a 
small number of distinct utterances. The longer an 
utterance is, the more easily it can be distinguished from 
other utterances. For example, distinguishing the isolated 
words hot , cut, and quit is difficult and error prone. 
Recognition performance also decreases as the language 
model grows. The larger the language model, the more 
time the recognizer must spend searching for a matching 
utterance and the larger the likelihood of two utterances 
in the language model sounding similar For best results, 
limit the size of the language model to fewer than a 
hundred phrases at any time and avoid including phrases 
that are easily confused when spoken, like "wreck a nice 
beach" and "recognize speech." 

DO SOMETHING DIFFERENT 

Compelling applications of speech recognition ore often 
novel ones, instead of simply paralleling an application's 
graphical user interface with a spoken one (making all 
menu items speakable, for example], do something 
different — something that takes advantage of the unique 
properties of speech. Combine speech synthesis with 
speech recognition to engage the user in a brief dialog. 
Use efficient language models to allow a single utterance 
to trigger a series of commands that might otherwise 
require interaction with dialog boxes, let the power of 
speech recognition augment the graphical Interface your 
users are already familiar with. Use your imagination! 


In Listing 4 t Han die Recognition DoaeAE, our Apple event handler, uses the routine 
AEGetParamPtr to extract the status of the result as well as the recognizer and 
recognition result objects from the Apple event. 

At this point, the Apple event handler could easily get the text of what was heard by 
getting the kSRTKXTFormat property of the recognition result. But a more useful 
form of the result is the kSRLanguageModel Format, This language model parallels 
the language model gTopLanguageModel, but instead of containing all of ihe phrases 
“Hello,” “Goodbye,” and “What rime is it?” it contains only a copy of the phrase 
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Listing 3. Building a simple language model 

OSErr BuildLanguageModel (void) 

{ 

GSErr status; 

const char kLMName[] = "<Top LM>"; 

/* First, allocate the gTopLanguageModel language model. */ 

status = SRNewLanguageModel(gRecognitionSystem, &gTopLanguageModel, kLMName, strlen(kLMName)); 
if (Istatus) { 

long refcon = kTopLMRefcon; 

/* Set the reference constant of our top language model so that when we process our */ 

/* recognition result, we'll be able to distinguish it from the rejection word, "???'% */ 
status = SRSetProperty(gTopLanguageModel, kSRRefCon, arefcon, sizeof(refcon))? 
if (1 status) { 

const char *kSimpleStrH = { "Hello", "Goodbye", "What time is it?", NULL }; 

char **currentstr = (char **) kSimpleStr; 

long refcon = kHelloRefCon; 

/* Add each of the strings in kSimpleStr to the language model, and set the refcon to */ 

/* the index of the string in the kSimpleStr array. */ 
while (*currentstr a a Istatus) f 

status = SRAddText(gTopLanguageModel, *currentstr, strlen(*currentStr), refcon-M-); 
t+currentStr; 

> 

/* Augment this simple language model with a fancier one, */ 
if (‘status) 

status = AddFancierLanguageModel{gTopLanguageModel); 

) 

} 

return status; 


Listing 4. Handling the recognition-done Apple event 

pascal OSErr HandleRecognitionDoneAE (AppleEvent *theAEevt, AppleEvent *reply, long refcon) 

{ 

OSErr recognitionStatus = 0, status; 

long actualSize; 

DescType actualType; 

/* Get recognition result status. */ 

status = AEGetParamPtr(theAEevt, keySRSpeechStatus, typeShortInteger, & actualType, 

(Ptr) arecognitionStatus, sizeof(recognitionStatus), &actualSize); 

/* Get the SRRecognizer. */ 
if (istatus a a IrecognitionStatus) ( 

SRRecognizer recognizer; 

status = AEGetParamPtr(theAEevt, keySRSecognizer, typeSRRecognizer, ^actualType, 

(Ptr) arecognizer, sizeof(recognizer), fcactualSize); 

(continued on next page) 
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Listing 4, Handling the recognition-done Apple event (continued} 

/* Get the SRRecognitianResuIt* */ 
if (Istatus) { 

SRRecognitionResult recResult; 

status = AEGetParamPtr(theAEevt, keySRSpeechResult , typeSRSpeeehResult, fractualType, 
(Ptr) trecResult, sizeof(recResult ) r sactualSize); 

/* Extract the language model from the result, */ 
if (Istatus) { 

SELanguageModel resultLM; 

long propertySize = sizeof(resultLM)? 

status - SRGetProperty(recResult, kSRLanguageModelFomat f &resultLM f fcpropertySize ); 

/* Process the language model, */ 
if (Istatus) { 

status ~ ProcessRecognitionResult{resultLM, recognizer); 

/* What we SSGot we must SRRelease! */ 

SRReleaseObject(resultLM); 

} 

/* Also release the recognition result, */ 

SRReleaseObject(recResult); 

} 

> 

return noErr; 


that was recognized. Fur example, if the user said “Goodbye,” the language model 
returned in the kSRLanguageModelFormat property would contain one phrase, 
which would have a kSRSpelling property of “Goodbye” and a kSRRefiCon property 
of 1 (the value passed for that phrase in the SRAddText call in Listing 3). The 
ProcessRecognitionResuk routine (Listing 5) uses the language model to determine 
what was said by getting the kSRRefCon property of the spoken phrase and 
responding appropriately. 

This example uses the SRSpeakAndDrawText routine to respond to recognition 
events. The Speech Recognition Manager uses the Speech Synthesis Manager to 
speak the string, and the animated feedback character (displayed in Apple’s standard 
feedback window) lip-synehs with the synthesized text. The Speech Recognition 
Manager also displays the response text in the feedback window. (You can use other 
routines to simply speak a string through the feedback window without displaying it, 
or to display a string without speaking it.) 

SETTING THE ACTIVE LANGUAGE MODEL AND STARTING TO LISTEN 

Ml w r e need to do now is make the language model weVe built, gTopLanguageModel, 
the active language model and tell our recognizer to start listening. First wre call the 
SRSetLanguageModel function, w r hicb associates gTopLanguageModel with the 
SRRecognizer weVe allocated, gRecognizen 

OSErr status - SRSetLanguageModelfgRecognizer, gTopLanguageModel); 
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Listing 5. Processing a recognition result 

OSErr ProcessRecognitionResult (SRLanguageModel resultLM, SRRecognizer recognizer) 

{ 

OSErr status = noErr; 

if (resultLM && recognizer) { 
long refcon; 

long propertySize = sizeof(refcon); 

/* Get the refcon of the root object */ 

status = SEGetFroperty(resultLM, kSRRefCon, fcrefcon, &propertySize); 

/+ Is the resultLM a subset of our top language model or is it the rejection word, "?7? w ? */ 
if (Istatus &S refcon == kTopLMRefcon) { 

SRLanguageObject languageObject; 
propertySize = sizeof(languageObject); 

/* The resultLM contains either an SRPhrase or an SRPath. We use the refcon property */ 

/* set in our language model building routine to distinguish between the results* */ 

/* Get the phrase or path. */ 

status - SRGetlndexedltemEresultLM , & languageObject, 0); 
if (Istatus) { 
long refcon; 

propertySize = sizeof(refcon); 

/* Get the refcon of the language object. */ 

status = SRGetProperty{languageObject, kSRRefCon, fcrefcon, &propertySize); 
if (Istatus) switch (refcon) { 
case kHelloRefCon: 
case kGoodbyeRefCon: 
case kWhatTimelsItRefCon: 

{ 

const char *kResponses[ ] - { ’’Hi there J", “Don't leave now I", 

time to use the Speech Recognition Manager I" 

}; 

/* Speak and display our response using the feedback character- */ 

/* Use the refcon as an index into our response array* */ 
status - SRSpeakAndDrawText(recognizer, kResponses[refcon], 
strlen(kResponses[refcon])); 

> 

break; 

case kCompanyRefCon: 

status - ProcessFancierLanguageMode1(languageObject, recognizer); 
break; 

} 

/* Always SRRelease what we SRGot. */ 
status = SRReleaseGbject{languageObject); 

} 

> 

} 

return status; 

} 
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You can build as many language models as you like, but there is always just one that’s 
active* You can make another language model active (and thereby deactivate the one 
that was previously active), or you can enable and disable parts of the active language 
model* Typically this is done in response to a speech-detected Apple event, sent to 
the application when recognition is about to begin* 

For a good example of making your language model dynamically conform to 
the context of your application, see the article "Adding Speech Recognition to on 
Application Framework" in this issue of develop.* 

Once w r eVe set the active language model, we start the recognition process by calling 
SRStartListening, as follows: 

if (1 status) 

status - SRStartListening(gRecognizer)? 

Now we can start speaking to our application. When an utterance is recognized as 
belonging to our language model, our Apple event handler, HandleRecognitionDoneAE, 
will be called and the recognition result will be processed. It’s that easy! 

CLEANING UP 

Listing 6 shows how to clean up when your application quits. In general, you should 
release the speech objects in the order shown* 

BUILDING FANCIER LANGUAGE MODELS 

The Speech Recognition Manager provides several routines that your application can 
use to create and manipulate fancier language models than the one created earlier in 
Listing 3, For example, suppose you wanted to create an application that responds to 
users when they say, “Tell me the price of <company> stock,” where <company> is 
one of several company names. 

To create a language model like this, your application needs to create an SR Path 
object that consists of the phrase “Tell me the price of”' followed by an embedded 
language model representing the company names, followed by the word “stock.” The 
AddFancierLanguageModcl function creates this path and adds it to the language 
model created in Listing 3* (Note that the embedded company language model is 
simply a list of phrases, just like the language model we created in Listing 3.) 

Figure 4 shows the structure of the entire language model. WeVe limited die number 
of companies to three here for simplicity. The top half of each box shows the spelling 
and refcon properties of each object; the lower half indicates the object type. 

Take a look at the AddFancierLanguageModel function (not shown, but included 
with our sample code) to see how to build the fancier language model* (Don’t worry if 
this routine seems like a lot of code just to add the command “Tell me the price of 
<company> stock”; below well describe the SRLanguageModder tool, which makes 
the creation of complicated static language models very easy.) Listing 7 shows how 
your application would process results given this fancier language model. 

Speech recognition applications that support utterances like “Tell me the price of 
<company> stock” or “Call <name>,” while limiting <company> or <name> to a few 
dozen items, can be more compelling than those that just respond to simple phrases* 
They’re nicely limited in scope, yet they allow the user to invoke actions more easily 
than would be possible with a graphical user interface. What other technology does 
that? 
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Listing 6, Terminating speech recognition 

void TerminateSpeechRecognition (void) 

{ 

OSErr status = noErr; 

/* If we have an active language model, release it. */ 
if (gTopLanguageModel) { 

status « SRReleaseObject(gTopLanguageModel); 
gTopLanguageHodel *= NULL; 

} 

/* If we have a recognizer, release it. */ 
if (gRecognizerJ { 

status » SRStopListening(gRecognizer); 
status = SRReleaseObject{gRecognizer}; 
gRecognizer - NULL; 

} 

/* If we have a recognition system, close it. */ 
if (gRecognitionSystem) { 

status = SRCloseRecognitionSystem(gRecognitionSystem); 
gRecognitionSystem = NULL; 

} 

/* Remove our Apple event handler and dispose of the handler's */ 
/* routine descriptor. */ 
if (gAERoutineDescriptor) { 

status = AERemoveEventKandler(kAESpeechSuite, kAESpeechDone, 

gAERoutineDescriptor, false); 
DisposeRoutineDescriptor(gAERoutineDescriptor); 
gAERoutineDescriptor = NULL; 

} 



Figure 4* Language model built by calling BuildLanguageModel 
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Listing 7 . Processing a recognition result given a fancier language model 

OSErr ProcessFancierLanguageModel (SRPath resultPath, SRRecognizer recognizer) 

f 

OSErr status = noErr; 

if (resultPath && recognizer) { 

SRLangxiageModel eompauyLM; 

/* Get the second item in the path — it's the company language model- */ 
s tatu s = SRGetIndexe d11em(resultPath, & c ompanyLM # 1}; 
if (Jstatus && companyLH) { 

SRP hra s e companyName; 

/* In the result language model, the company language model contains just one phrase- */ 
status = SRGetIndexedItern(companyLM, &companyName, 0); 
if (I status) { 
long refcon? 

long propertySize = sizeof(refcon); 

/* Get the refcon from the company name- It's our index into the response array* */ 
status = SRGetProperty(companyName, kSRRefCon, Grefcon, GpropertySize); 
if (■status) { 

const char *kResponses[j = 

{ "Apple stock is priced to move i *, 

"Netscape is trading at fifty dollars**, 

"Why would you want to know that?" 

>f 

status = SRSpeakAndDrawText(recognizer, kResponses[refcon], 
strlen(kResponses[refcon])); 

} 

/* What we SRGot we must SRRelease- */ 
status = SRReleaseObject(companyName); 

} 

status - SRReleaseObjectfcompanyLH); 

> 

} 

return status; 

> 


MANIPULATING LANGUAGE MODELS 

The Speech Recognition Manager contains several more routines and properties for 
manipulating language models* We'U look at a few of them here. 

Your application can create a large language model and then use the SRSetProperty 
function to disable and enable parts of it quickly on the fly as shown in Listing 8, By 
enabling only parts of a language model, you can minimize the number of utterances 
that the recognizer is listening for 

Your application can change, clear, or rebuild parts of a language model dynamically 
to reflect the current context of your program. Listing 9 clears and then rebuilds the 
company language model that w r as originally built by die AddFancierLanguageModel 
function. 


18 develop fasue 27 September 1996 








Listing 8. Disabling a part of a language model 

/* Disable the stockPath part of the gTopLanguageModel. */ 

/* The stock path is the fourth item in this language model. */ 

SRPath stockPath; 

OSErr status = SRGetIndexedItem{gTopLanguageModel, &stockPath, 3); 

if (■status) { 

Boolean enabled = false; 

status = SRSetProperty(stockPath, kSREnabled, ^enabled, 

sizeof(enabled)); 

/* Balance SRGet call. */ 

status = SRReleaseObject(stockPath); 


Listing 9. Emptying and refilling the company language model 

/* Empty and refill the embedded company language model* */ 

/* Assume that stockPath has already been initialized* */ 

/* The companyLM is the second item in the stock path* */ 
ERLanguageModel companyLM; 

OSE rr statuses RGe tin dex edItern(s toe kP at h , £ c orapanyLM, 1); 

if (J status) { 

/* This releases each phrase in the company language model* */ 
status - SREmpt yLa nguageOb j ec t(c omp a n yLM); 

/* Now rebuild the company language model with new companies* */ 
if (1 status) { 

const char *kNewCompanies[] = { "IBM", "Motorola", 

"Coca-Cola", NULL }; 

char **company = (char **) kNewCompanies; 

long refcon = 0; 

while (^company && lstatus) { 

status = SRAddText(companyLM, *company, strlen(*company), 
refcon++); 

t+company; 

} 

> 

SRReleaseObject(companyLM); 


At any given moment, the active language model should be relatively small, but your 
application can change the set of active phrases at any time* For example, if a Web 
browser application made its links speakable, at any given moment there would only 
be a few dozen visible links, so there would only be a few dozen phrases active. But if 
you spent a couple of hours surfing the Web wi th that browser, you would have seen 
many thousands of links throughout the session, and you could have spoken any one 
of them while it was visible* 
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In addition to enabling and disabling parts of your language model, the SRSetProperty 
function allows your application to make words, phrases, paths, or language models 
repeatable (so that the user can say that item one or more dines in a row) or rejectable 
(so that if the user says something else for that item, the recognizer will fill it in with 
a special rejection word with a spelling of “???”). 

Your application can also make any word, phrase, path, or language model 
optional by setting the corresponding object's kSROptional property to true. In 
AddFancierLanguageModel, we've set the kSROptional property of the SRWord 
“stock” to true, so the recognizer is ready for the user to say, “Tell me the price of 
Apple” as well as “Tell me the price of Apple stock.” 

Your application doesn't have to build language models from scratch each time it 
runs. The Speech Recognition Manager provides routines for saving and loading 
language objects (for example, the SRPutLanguageObjectlntoHandle and 
SRNewLanguageObjeetFromDataFi!e routines). Listing 10 shows an example. 


Listing 10* Saving a language model into a resource 

/* Allocate a handle of size 0 to store our language model in; */ 

/* SRPutLanguageObjectlntoHandle will resize it as needed. */ 

Handle ImHandle = NewHandle(0); 

OSErr status = MemError{); 

if ("status) { 

status = SRPutLanguageObjectlntoHandle(gTopLanguageModel, ImHandle); 
if ("status) { 

/* Save the language model as a resource in the current */ 

/* resource file. Pick a reasonable resource type and ID, */ 
AddResource(ImHandle, f LMDL', 100, H \pTop Language Model"); 

/* Make sure it gets written to disk. */ 
if ([(status = ResError{))) { 

WriteResource(ImHandle); 

DetachResource(ImHandle); 

} 

} 

DisposeHandle(ImHandle); 

> 


Apple provides a very handy developer tool, called SRLanguageModeler, that you can 
use to quickly create, test, and save language models into resources or data files. You 
can find this tool, and documentation for it, with the other Speech Recognition 
Manager developer information on this issue's CD and on the speech technology 
Web site. SRLanguageModeler lets you write out a language model in a relatively 
simple text form and then try it out to see how well its phrases can be recognized and 
discriminated from one another. It lets you save the language models into a binary 
resource or fde format that you can ship with your application. Your application can 
load the language model at run time with SRNewLanguageObjectFromHandle or 
SRNew LanguageObjectFromDataFile. SRLanguageModeler will eliminate a lot of 
die code you would otherwise have to write to construct the static parts of your 
language models. 
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SPEECH: THE FINAL FRONTIER 

If you’ve understood this article, you'll have no problem making practical use of 
speech recogni tion in your application. From the basics of checking for the proper 
version of the Speech Recognition Manager to some of the finer details of building 
language models, we've shown you everything you need to know to get started. Be 
sure to take a look at the SR Sample application, which uses many of the listings in 
this article. 

To dig even deeper, check out the Speech Recognition Manager documentation and 
the SRLanguageModeler tool. For dps on using die Speech Recognidon Manager 
within an application framework and dynamically changing your language model, see 
the article “Adding Speech Recognition to an Application Framework” in this issue of 
develop. Then have fun turning your application into a good listener. 


RELATED READING 

* "Speech Recognition Manager," on this issue's CD and on Apple's speech 
technology Web site, http://www.speech.apple.com. 

* "Adding Speech Recognition to an Application Framework" by Tim Monroe, in 
this issue of develop . 


Thanks to our technical reviewers Mike Dlfts, Eric 
"Braz" Ford, Tim Monroe, and Guillermo Ortiz.* 



Make your products 
stand out from the crowd. 



Add a new dimension to your products with 
Apple’s speech technologies. 


Apple’s Speech Development Kits are online and 
freel Create speech-savvy applications that engage 
your customers and draw them into rich, 
immersive environments. Apple's Speech APIs let 
you incorporate speech recognition and synthesis 
into your applications quickly and easily. Master the 
power of Apple s speech technology today, 
Download the free Speech Development Kits at 
h t tp ://www.speech, appl e .com. 

The Apple Speedi Devekipmem Kits include ihe Speech 
Remgnitkjri Manager, the Speech Synthesis Manager, APIs 
ctfafisitms, Simple code, [lhnne\ jncl tkxnjmenLiiinn. 

(Online service jtrttl computer not included.) 


f * r i 




9 T r 


Apple Computer,Inc. 


C/Wfi tfqi* OmfftUtK fm fights mmtit Apffr, toga* I’lamMb mulRmvr Maostash are ttj^skTvd Jummourtc of oaiNpu^T Ihl. .Uul is a inttkmurh qfAppfc CanptUtt. 


THE SPEECH RECOGNITION MANAGER REVEALED 2 1 


























Adding Speech Recognition to on Application 
Framework 


It's easy to add speech recognition capabilities to an application built with 
an object-oriented framework, with minimal disruption to your existing 
code. To illustrate the process, this article shows one way to add basic 
speech recognition capabilities to an application built with PowerPlant, 
Metrowerks' popular C++-based application framework. You can use 
the same strategy with other application frameworks as well. 



TIM MONROE 


Speech recognition capabilities, such as those provided by Apple’s Speech Recognition 
Manager, promise to revolutionize die way people use computers. The reason for this 
is simple: it’s often a lot easier to say what you want done than to actually do it, even 
in the “user-friendly” environment provided by the Macintosh graphical user interface. 
So the time you spend making your application speakable is time very well spent 
Happily, if you've built your application with a framework such as PowerPlant or 
MacApp, you can add basic speech recognition capabilities quickly and easily 

To show how to add speech recognition to an application built with a framework, weil 
modify the PowerPlant DocDemo sample provided with the CodeWamor 8 release 
to add speech support for the File menu commands. Of course, there’s nothing special 
about DocDemo: you should be able to drop the code we provide into any PowerPlant 
application. Moreover, although this code is specific to PowerPlant, you should be 
able to use similar techniques with other application frameworks as well. 


Before reading this article, you should be familiar with the basic operations of the 
Speech Recognition Manager and with the PowerPlant application framework. For 
an overview of the Speech Recognition Manager, see the article “The Speech 
Recognition Manager Revealed” in this issue of develop . As mentioned in that article, 
you’ll find everything you need to use the Speech Recognition Manager’— including 
detailed documentation (written by yours truly) — on diis issue’s CD and on Apple’s 
speech technology Web site at http://www.speech.apple.com. For basic information 
about PowerPlant, see The PowerPlant Book or other MetrowerLs documentation. 


THE BASIC STRATEGY 

We want to add speech support for the File menu commands in the DocDemo 
application. This isn’t the highest or best use of speech recognition capabilities (see 
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“Speakable Menus?”), but it makes a simple example for us to focus on. In a nutshell, 
well define a custom C++ class and create a single instance of that class to handle all 
the required speech recognition processing (such as installing a language model and 
responding to recognition results sent to it via Apple events). Here are the steps we’ll 
follow: 

1. Add a few lines of code to the main application source code file, 
CDocDemoApp.cp. In part, this code creates a single instance of our 
custom class CDocSpeech. 

2 , Design a set of language models that describe die words and phrases we 
want to listen for. 

3, Add resources containing string representations of those words and 
phrases to the application’s resource file. 

4. Write Apple event handlers for the two speech recognition events. 

The following sections explain these steps in detail, though not strictly in this order. 
All the code provided here is also included on this issue’s CD. 


HOOKING UP WITH THE MAIN APPLICATION 

All the speech recognition processing for our PowerPlant-based application will be 
handled by a single custom object of type CDocSpeech, The main application code 
needs only to create (and later delete) that custom object. We’ll start by adding 
these lines of code to the beginning of the main application source code file, 

C D ocDe mt >App. cp: 

#include "CDocSpeech.h" 

extern CDocSpeech *gDocSpeechQbj; 

Boolean gHasSpeechRecog; 

The external reference is to an instance of the CDocSpeech class, and the Boolean 
global variable indicates whether the Speech Recognition Manager is available in the 
current operating environment. To set that variable and create our custom object, we 
add the code in Listing 1 to the constructor CDocDemoApp::CDoeDemoApp, 

Well also need to delete gDocSpeechObj when our application quits. We do this by 
adding the following code to the destructor CDocDemoApp::~CDocDemoApp: 


SPEAKABLE MENUS? 

While it's fairly easy to make your application's menus 
speakable, this isn't necessarily the best use of speech 
recognition technology and it's definitely not what Apple's 
speech engineers would like to see you focus your 
attention on. Most File and Edit menu commands ore just 
too short to be easily distinguished by the recognizer 
("quit' 1 sounds a lot [ike "cut," for example). 

In addition, since menus can't be seen without pulling 
them down, novice users probably won't know which 
menu commands are available until they click in the 
menu bar; at that point, they may as well just use the 
menu. 


However, there is some value in knowing how to make 
menus speakable. For one thing, the techniques used in 
this article can easily be extended to handle more 
complex utterances that have nothing to do with menus. 
Also, there is real value in making tool palettes —- which 
are really just graphical menus that happen to Float on 
the desktop — speakable; for an example, see the demo 
program PlacMoc on this issue's CD. 

So the moral is: moke your menus speakable if you think 
there is value for the user, but don't just make your menus 
speakable. Do something creative and compelling with 
speech recognition. 
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// Shut down speech recognition , if it's running, 
if (gEasSpeechRecog) 
delete gDocSpeechObj; 

Those are all the modifications we need to make to our existing source code! The rest 
of the speech processing is handled by the custom speech recognition object created 
by our main application code. 

DEFINING A SPEECH RECOGNITION CLASS 

The header file CDocSpeech.h, shown in Listing 2, defines a number of constants 
specifying the 'STR# 1 resources (and indices within those resources) that contain die 
names of the language models we want to create and the actual words or phrases we 
want to listen for. We T ll use these constants later* when we create the various 
language models. 


Listing 1 . Creating a custom speech recognition object 

// Determine whether the Speech Recognition Manager is available; 
// if it* a available, create a custom speech recognition object, 
long theVersion; 

OSErr theErr; 

gHasSpeechRecog = false; 

theErr ~ ::Gestalt(gestaltSpeechRecognitionVersion, ktheVersion); 
// Version must be at least 1.5.0 to support API used here, 
if (1theErr) 

if (theVersion 0x00000150) { 
gHasSpeechRecog = true; 
gDocSpeechObj = new CDocSpeech(); 

} 


Listing 2 . Specifying ’SIR#’ resources and declaring CDocSpeech 


#include "SpeechReeognitian.h" 


// Language model names 


const ResIDT 
const short 
const short 
const short 
const short 
const short 


rSTR_LMNames 
kStr_GApplLM 
kStr_GUnivLM 
kStr_GDocuLM 
kStrUFileLM 
kStr DFileLM 


=400; //ID of STR# resource 

= 1; // Indices within resource 

= 2 ? 

= 3; 

- 4; 

= 5; 


// Universal file command phrases 


const ResIDT kSTRUFileCmds = 500; 

const short kStr_New = 1; 

const short kStr_Open - 2; 

const short kStr_PageSetup - 3; 

const short kStr_Quit = 4; 


// ID of STR# resource 
// Indices within resource 


(continued on next page) 
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Listing 2. Specifying 3 STR# 1 resources and declaring C Doc Speech (continued) 


// Document file command phrases 


const ResIDT 

kSTR DFileCmds 

= 

501; 

// 

ID of STR# resource 

const short 

kStr Close 

= 

1 


n 

Indices within resource 

const short 

kStr_Save 

= 

2 




const short 

kStr SaveAs 

= 

3 




const short 

kStr Revert 

= 

4 




const short 

kStr^Print 

= 

5 




const short 

kStr PrintOne 

= 

6 




// Apple menu 

command phrases 






const ResIDT 

kSTR_UApplCmd s 

= 

503? 

// 

ID of STR# resource 

const short 

kStr About 

= 

i; 

■ 

// 

Indices within resource 

Idefine kEnableObj 

true 



Idefine kDisableObj 

false 




class CDocSpeech { 
public: 

virtual 

static pascal OSErr 

static pascal OSErr 

private: 

OSErr 

>? 


CDocSpeech(J ; 

-CDocSpeech{}; 

HandleSpeechBegunAppleEvent f AppleEvent 

*theAEevt, AppleEvent *reply, long refcon); 
HandleSpeechDoneAppleEvent (AppleEvent 

*theAEevt, AppleEvent *reply, long refcon); 

MakeLanguageModeIs {void); 


CDocSpeech.h also contains the declaration of the custom CDocSpeech class. 
CDocSpeech is extremely simple: it contains a constructor, a destructor, and two 
Apple event handlers* It also defines a private method, MakeLanguageModels, that 
creates the language models used by DoeDemo. xMakeLanguageAlodels is called by 
the constructor when an instance of the CDocSpeech class is created. 

All the remaining code is found in the file CDocSpeech.cp. Listing 3 shows the 
beginning of that file, which declares all the global variables and function prototypes. 


Listing 3. Declaring global variables and function prototypes 

#include "CDocSpeech.h* 

// Global variables 
SRRecognitionSystem 
SRRecognizer 
SRLanguageMode1 
SRPhrase 
CDocSpeech 

// Function prototypes 

void SetLanguageObjectState (SRLanguageQbject inObj, Boolean isEnabled); 


gSystem; 
gRecognizer; 
gGApplLM r gGDocuLM; 
gRevert; 

*gDocSpeechGbj = nil; 
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The constructor method, shown in Listing 4, performs all the necessary startup 
associated with speech recognition. Much of this code should already be familiar to 
you from the article “The Speech Recognition Manager Revealed,” 

Now we just need to write the MakeLanguageModels function called by the 
CDocSpeech constructor, and the two ±\pple event handlers. 


Listing 4. Starting up speech recognition 

CDocSpeech::CDocSpeech() 

{ 

OSErr theErr = naErr; 


// Open a recognition system. 

theErr = ::SRGpenRecognitionSystem(SgSystemi kSRDefaultRecognitionSystemlD); 


// Set recognition system properties to user-selected feedback and listening modes, 
if (jtheErr) { 

short theModes = kSRHasFeedbackHasListenModes; 

theErr = ::SRSetProperty(gSystem, kSRFeedbackAndListeningModes, &theModes, sizeof[theModes]); 

} 

// Create a recognizer with default speech source, 
if [JtheErr) 

theErr = ::SRNewRecognizer(gSystem, figRecognizer, kSRDefaultSpeechSource); 

// Set recognizer properties. We want to receive notifications when recognition begins and ends, 
if (ItheErr) { 

unsigned long theParam = kSRMotifyRecognitionBeginning j kSRflotifyReeognitionDone; 
theErr = ::SR3etProperty(gRecognizer, kSRNotificalionParam, fctheParam, sizeof(theParam)); 


// Install Apple event handlers* 
if (JtheErr) { 

theErr = ::AEInstallEventHandler(kAESpeechSuite, kAESpeechDetected, 

NewAEEventHandlerProcfHandleSpeechBegunAppleEvent), 0, false); 
theErr = :tAEInstallEventHandler(kAESpeechSuite, kAESpeechDone, 

NewAEEventHandlerProc(HandleSpeechDoneAppleEvent), 0, false); 

> 


// Make our language models, 
if (ItheErr) 

theErr = MakeLanguageModels(); 

// Install initial language model and release our reference to it. 
if (ItheErr) { 

theErr - ::ERSetLanguageModel(gRecognizer, gGApp1LM); 

::SRReleaseObject(gGApplLM); 


// Have the recognizer start processing sound, 
if (ItheErr) 

theErr = ::SRStartLi$tening(gRecognizer ); 
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CONSTRUCTING THE LANGUAGE MODELS 

Probably die most time-consuming pare of adding speech recognition to an application 
is defining the language models that describe the words and phrases you want to listen 
for. The process is straightforward, but it requires careful attention to the various 
states your application can be in. This is because you want the active language model 
to include only utterances that make sense at any given time. For instance, if no 
document window is open, it makes no sense to listen for the Close or Save command* 
Similarly, if a document isn’t dirty (that is, if it hasn’t changed since it was most recently 
saved), you probably don’t want the user to be able to execute the Revert command. 

This should remind you, of course, of the context-specific menu enabling and disabling 
that's a standard part of any good Macintosh application. For our demonstration 
application, we’ll handle context sensitivity by creating a number of embedded 
language models that we’ll enable or disable according to context. 

The commands in the File menu fall into mo main categories: those that can be issued 
at any time (such as New or Open) and those that apply to a specific document (such 
as Save or Close). Accordingly, we’ll construct two language models, one for each type 
of command. Let’s call the first variety universal file commands and the second variety 
document file commands . In addition, we want to make the About DocDemo command 
utterable. FI ere’s a Backus-Naur Form (BNF) diagram of our top-level language model: 

<Menu Commands:* = <Universal Commands> | cDocmnent Commands:*? 

<Universal Commands> = <UniversaI File Commands> | About DocDemo; 

Universal File Commands:* - New [ Open | Page Setup | Quit; 
cDocument Commands> = <Document File Commands:*; 

document File Commands:* = Close | Save j Save As | Revert | Print | 

Print One? 

As you can see, the top-level language model Menu Commands consists of wo 
embedded language models, one for commands that can be issued at any time and one 
for commands that require a document window to be open. Each of these embedded 
language models contains other language objects. The Universal Commands language 
model contains the phrase “About DocDemo” and die language model that contains 
the universal file commands. The Document Commands language model contains 
only the language model that contains the document file commands; you would 
add other document-specific models here (for instance, document-specific editing 
commands). In all, we’ll create five language models. (Note that the Page Setup 
command is in the universal file commands language model; that’s because DocDemo 
allows you to choose that command even if no document window is open.) 

Listing 5 shows the code defining the MakeLanguageModels function (error 
checking has been removed for die sake of readability). Apple provides a utility, 
SRLanguageModeler, that you can use to build and test language models described 
with BNF diagrams like that shown above. SRLanguageModeler can also save those 
language models into resources or files, from which your application can load the 
models at run time. Here, however, we build the language models on the fly to 
demonstrate the Speech Recognition Manager routines for doing so. 

MakeLanguageModels begins by calling SRNewLanguageModel five times to create 
the five new, empty language models. (As indicated earlier, the names of the language 
models are read from the application’s resource fork) Then MakeLanguageModels 
creates a language object for the single word revert , as follows: 

::GetIndString{theStr, kSTRDFileCmds , kStr^Revert}; 

; :SRNewPhraBe(gSystein, SgRevert, &theStr[l], theStr[0J)? 
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Listing 5, Creating the language models 

GSErr CDocSpeech::MakeLanguageModels [void} 

{ 

OSErr theErr - noErr; 

Str255 theStr; 

SRLanguageModel myGUnivLM, myDFileLM, myDFileLM; 

// Make the language models (which are initially empty), 

;:GetlndString{theStr, rSTR_LMNamea, kStr_GApplLM); 

::SRNewLanguageModel(gSystem, & gGApplLM, fctheStr[ 1 ], theStr[0]); 

::GetlndString(theStr, rSTR_LMNames, kStr_GUnivLM); 

::SRNewLanguageMode1(gSys tern, £myGUnivLM, fctheStr[1], theStr[0]}; 

:: GetlndString (theStr, rSTR_LMK antes , kStr_UFileLM) ; 

::SRNewLanguageMode1(gSys tem, SmyDFileLM, & theStr[1], theStr[0]); 

;: GetlndString (theStr, r5TR_LMNames f kStr_GDocuLM); 

:: SRMewLaoguageModel(gSystem f fcgGDocuLM, StheStr[ 1 ], theStr[0]); 

;;GetlndString(theStr, rSTR LMMantes , kStr DFileLM); 

:: SRNewLanguageModel(gSystem, ^myDFileLM, &theStr[ 1 ] , theStr [ 0 ]); 

// Make any other language objects we‘11 need* 

:sGetlndStringftheStr, kSTRDFileCmds, kStr Revert); 

::SRNewPhrase(gSystem, & gRevert, &theStr[ 1 ], theStr[0]); 

// ****<universal File Commands>**** 

::GetlndString[theStr, kSTRJJFileCmds r kStr_New); 

: t SRAddText(myUFileLM, &theStr(1], theStr[ 0 ], cmd_New); 
i;GetlndString(theStr f kSTR_UFileCmds , kStr_Open); 

::SRAddText(myDFileLM , & theStr(1], theStr[0], cmd_Gpen); 
i:GetIndString(theStr, kSTRJJFileCmds, kStr_PageSetup); 

::SRAddText(myDFileLM, £theStr[1j, theStr[0], cmd J?ageSetup); 

;:GetlndString(theStr, kSTRJJFileCrads , kStrJJuit); 

::SRAddText(myDFileLM, 6theStr[l], theStr[0], cmdQuit); 

// ****<Document File Commands>**** 

::GetIndString{theStri kSTRJJFileCmds, kStrClose); 

SRAddText[myDFileLM, fitheStr[l], theStr[0], cmd Close); 

GetlndString(theStr, kSTRJ)FileCmds, kStr_Save); 

:;SRAddText{myDFileLM, 6 theStr[1j f theStr[0], cmd Save); 

: t GetlndString(theStr, kSTRDFileCmds, kStrSaveAs); 

::SRAddText(myDFileLM, £theStr[l], theStr[0], cmd_SaveA.s); 
unsigned long theRefCon - cmdRevert; 

::SRSetProperty(gRevert, kSRRefCon, &theRefCon, sizeof[theRefCon)); 

<:SRAddLanguageObject(myDFileLM, gRevert); 

::GetlndString(theStr, kSTR_DFileCmds, kStrFrint); 
s:SRAddText(myDFileLM, fitheStr[l], theStr[0], cmd_Print); 

::GetlndString[theStr, kSTR_DFileCmds, kStrPrintOne); 

;;SRAddText(myDFileLM, &theStr[lJ, theStr[0], cmd_PrintOne); 

// ****<0 OCUmen t Commands>***+ 

<:SRAddLanguageObject(gGDocuLM, myDFileLM); 

(continued on next page) 










Listing 5* Creating the language models (continued) 

// ****<universal Commands>**** 

::SRAddLanguageObject(myGUnivLM , myUFileLM); 

::GetlndString(theStr, kSTR_UApplCmds, kStr_About); 

::SRAddText(myGUnivLM, & theStr[ 1 ], theStr[01, cmd_About J ? 

// ****<Menu Cominands>**** 

::SRAddLanguageObj ect(gGApplLM f myGUnivLM}; 
r:SRAddLanguageObj ect(gGApplLM, gGDocuLM }; 

// Release any embedded language models we won't need later* 
::SRReleaseObj ect(myDFileLM ); 

:i SRReleaseObject(myUFileLM); 

::SRReleaseObject(myGUnivLM); 

return theErr; 

} 


We treat the Revert command specially because we want to listen for it only when an 
open document has a file associated w T ith it (and, of course, when the document is 
dirty"). Even when the Document Commands language model is active, the Revert 
command might need to be disabled. 

Next, MakeLanguageModels builds the two language models Universal File Commands 
and Document File Commands, In both cases, it simply adds tlie relevant words or 
phrases, read from resources, to the language model, like this: 

:iGetIndString{theStr, kSTRJJFileCmds, kStr_New); 
i: SRAddText(myUFileLM, StheStr[l], theStr[0], cmd_New); 

SRAddText sets the reference constant property of the specified language object to the 
value passed in its fourth parameter. In this example, the reference constant for the 
New command is set to the value cmd_New, which is a constant defined by PowerPIant. 
As you’ll see later, we’ll use that value to get PowerPIant to react appropriately to the 
user’s utterances. If you don’t use SRAddText, you need to explicitly set an object’s 
reference constant property, as is done for the Revert command: 

unsigned long theRefCon = cmd_Revert; 

::SRSetProperty(gRevert, kSRRefCon, ^theRefCon, sizeof(theRefCon)); 

::SRAddLanguageOb j ect(myDFileLM, gRevert); 

Once the two main language models have been created, the hierarchy displayed in the 
BNF diagram is established by a series of calls to SRAddLanguageOb)ect. 


ENABLING AND DISABLING THE LANGUAGE MODELS 

When a user begins speaking, your application is notified via a speech-detected 
Apple event. In general, your speech-detected event handler should determine what 
state your application is in and set the active language model accordingly. As w r e’ve 
mentioned, we’ll use this opportunity to enable or disable embedded language models 
{or even single words) to limit the recognizable utterances to those that make sense at 
the time. Listing 6 show^s our speech-detected Apple event handler. 
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Listing 6. Handling speech-detected Apple events 


pascal GSErr CDocSpeech i :HandleSpeechDetectedAppleEvent 

(AppleEvent *theAEevt, AppleEvent *reply, long refcon) 


{ 


ipraqma unused(reply, refcon) 


long 

DescType 

OSErr 

SRRecognizer 

LWindow 


actualSize; 
actualType; 
theErr - 0, 
theRec; 

*theWindow; 


recStatus = 0; 


// Get status and recognizer. 

theErr = ::AEGetParaMPtr(theAEevt, keySRSpeechStatus , 

typeShortInteger, &actuaIType , (Ptr)&recStatus, 
sizeof(recStatus), sactualSize); 
if (itheErr && JrecStatus) 

theErr a ;:AEGetFaramPtr(theAEevt t keySRRecognizer, 

typeSRRecognizer, &actualType, (Ptr)&theRec, 
sizeof(theRec), iactualSize); 

if (theErr) 
if (ItheRec) 

return theErr; 


// Figure out what state we're in; then enable or disable the 
// appropriate language models* 

theWindow = UDesktop:;FetchTopRegular(); // Look for a doc window, 
if (theWindow 1= nil) { // There is a doc window. 

SetLanguageObj ect State(gGDocuLM, kEnableOb}); 

// Turn off "Revert 1 ' if there's no file or it isn't dirty. 
Boolean isEnabled, outUsesMark; 

Chari 6 outMark; 

Str255 outName; 


LCoinmander t : Get Target () ->FindCommandStatus (cmd_Rever t r isEn abl ed f 

out Uses Mark, ou tMar k, ou tN ame ); 
SetLanguageOb j ectstate(gRevert f isEnabled); 

} else // There is no doc window. 

SetLanguageObj ectstate(gGDocuLM, kDis ableObj); 

// Now tell the recognizer to continue, 
theErr = :sSRContinueRecognition(theRec); 
return theErr; 


The event handler, HandleSpeechDetectedAppleEvent, calls the PowerPlant utility 
function UDesktopnFetchTopRegular to get die top document window. If there’s an 
open document window, HandleSpeechD etecte dAppleEvent calls die appli cation - 
defined function SetLangTiageObjectState to enable die Document Commands 
language model. Otherwise, if no document window is open, the event handler calls 
SetLanguageOb)ectState to disable diat language model. Listing 7 shows the simple 
function S etLa n gua geO bj e ct S la te, 







Listing 7* Enabling or disabling o language object 

void SetLanguageObjectState (SRLanguageObject inQbj, Boolean isEnabled) 

< 

Boolean theState - isEnabled; 

:;SRSetProperty[inObj, kSREnabled, & theState, sizeof[theState)); 

> 


Notice that if a document window is open, we need to determine whether to enable 
the Revert command* HandleSpeechDetectedAppleEvent cleverly calls the document 
window’s Find Command Status function to determine this* 

Instead of disabling the Revert command when it isn’t relevant, we could just let the 
recognizer keep listening for it but ignore it when the frontmost document, if any, 
isn’t dirty or has no file* This alternate strategy has some advantages* In particular, if 
the user says “revert” but we aren’t listening for that command, the recognizer might 
think the user has uttered some other command (like “quit” or “print”)* These 
misfires are much less likely to occur if the recognizer is listening for “revert” in 
addition to the other document file commands. 

If you think that a user is apt to utter a particular command at an inappropriate time, 
it’s probably better to ignore it than to disable it. On the other hand, we don’t want to 
make the active language model too big, and one way to keep its size manageable is to 
enable or disable parts of it according to context* That’s the strategy we’ve adopted 
for this article. Our sample application doesn’t listen for the Revert command unless 
it’s appropriate, to illustrate how to enable and disable language objects. 

HANDLING RECOGNITION RESULTS 

So far, we’ve defined our language models and set up the mechanism by which 
relevant parts of the language models are enabled or disabled according to context* 

All that remains is to do the right thing when the recognizer recognizes an utterance* 
Our application is informed of successful recognitions via recognition-done Apple 
events* Listing 8 shows the DocDemo recognition-done event handler* 


Listing 8* Handling recogniHon-done Apple events 

pa seal 0 SErr C Doc Spe ec hisHand1eRe cognitionDon e&pp1eE ve nt 

{AppleEvent *theAEevt, AppleEvent *reply, long refcon} 

V 

fpragma unused[reply, 

refcon) 

long 

actualSize; 

DescType 

actualType; 

OSErr 

theErr * 0 r recStatus “ 0; 

SRRecognitionResult 

recResult = nil; 

Size 

theLen; 

SRPath 

thePath; 

SRSpeechGbject 

theltem; 

long 

theRefCon; // Reference constant of item 


(continued on next page) 
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Listing 8* Handling recognition-done Apple events (continued) 

// Get status* 

theErr = ;:AEGetParamPtr(theAEevt, keySRSpeechStatus T 

typeShortInteger, SactualType, (Ptr)&recStatus, 
sizeof(recStatus), sactualsize); 

If Get result. 

if (JtheErr && \ recStatus) 

theErr = i;AEGetFaramFtr(theAEevt , keySRSpeechRes ult r 

typeSRSpeechResult, fcactualType, (Ptr)firecResult, 
sizeof(recResult), sactuaisize ); 

// Get command from result by reading the reference constant 
// of the relevant object, 
if (!theErr && lrecStatus) { 

:iSRGetFroperty(recResult f kSRPathFormat f kthePath, StheLen); 
theErr = ::SRGetIndexedItem(thePath, Sthelfcem, 0); 
if (1theErr) { 

theLen = sizeof(theRefCon); 

:iSRGetFroperty(theItem, kSRRefCon, ktheRefCon, stheLen); 

::SRReleaseObject(theltem); 

> 

// Release recognition result, since we f re done with it. 

:;SRReleaseObject(recResult); 
i :SRReleaseObject(thePath); 

} 

// Send the reference constant up the chain of command* 
LCommander::GetTarget()->0beyCommand((Message?)theRefCon, nil); 

return theErr; 


The interesting thing in this event handler is how utterly simple the important code 
is: all it does is extract the reference constant value of the recognized utterance and 
send that value up the PowerPlant chain of command* For example, if the recognized 
utterance is the word new, the reference constant is the value cmd_New, which is sent 
to a commander. In this case, the DocDemo application creates a new document. In 
effect, the CDocSpeech object does its work by calling code already in the DocDemo 
application* 

THE LAST WORD 

As you Ve seen, it's easy to add basic speech recognition for File menu commands to a 
PowerFlant application, largely because our custom speech object can simply issue 
die same commands that would be issued in response to a menu choice* You should 
now be able to add speech support for Edit menu commands and for any other menu 
commands supported by your application. 

Only one method remains to discuss, the destructor for the CDocSpeech class. The 
destructor simply stops recognizing utterances and closes down the recognition 
system opened by the constructor, as shown in Listing 9* 







Listing 9 , Shutting down speech recognition 

CDocSpeech;; CDocSpeech(} 

{ 

::ERStopListening(gRecognizer); 

::SRReleaseObjectfgRecognizer); 

::SRReleaseObject(gGDocuLH); 

::SRReleaseObject(gRevert); 

::SRCloseRecognitionSystem(gSystem ); 

} 


’NufFsaid. 


RELATED READING 

* "'The Speech Recognition Manager Revealed" by Matt Poliakoff and Aria Reeves, 
in this issue of develop. 

* "Speech Recognition Manager/' on this issue's CD and on Apple's speech 
technology Web site, http://www r speech,applexom. 

* The PowerPlant Book by Jim Trudeau, in Inside PowerPlant for CWB (Metrowerks, 
19 95}. 


Thank s to our technical reviewers Mike Dilts, 
Guillermo Ortiz, Matt Paliakoff, Ado Reeves, and 
Brent Schorsch. ’ 
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developers might be having? Why not show it oil by writing 
about it in develop} 

If you're a lot better at writing code than writing articles, don’t 
worry. An editor will work with you. The result will be something 
you’ll be proud to show your colleagues (and your Mom). 

So don’t just sit on those great ideas; feel the thrill of seeing them 
published in developl 

To receive our Author’s Guidelines, editorial schedule, and 
information about our incentive program, please send a message 
to develop@apple.com, or write Caroline Rose, Apple Computer, 
Inc., 1 Infinite Loop, Cupertino, CA 95014. 
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PRINT HINTS 


The All-New 
LaserWriter Driver 
Version 8.4 


DAVE POLASCHEK 


By the time you read diis, version 8,4 of the LaserWriter 
8 printer driver will have shipped. This driver — 
LaserWriter version 8,4, for short — is not die same 
old LaserWriter driver; ii has new features that 
developers have been asking for, sports a new user 
interface, and beats earlier versions of the driver in the 
quarter mile. 

Here I’ll outline some of the changes — a few minor, 
a few major that you need to he aware of for 
compatibility reasons. Even if you don’t want to take 
advantage of any of the great new features, you’ll at 
least need to address compatibility issues it any of the 
changes cause problems with your application. 

To help you implement die new features, this column 
is backed up with detailed documentation on this 
issue’s CD. 

THE EXTENDED PRINT RECORD 

The 120-byte print record in the previous driver 
version doesn’t have as many free hits available as some 
programmers would like. So to let you save all possible 
printing information about a document, Apple decided 
to allow for extensible print records. 

I fall you want to do is maintain compatibility with the 
new driver version, you shouldn’t need to change your 
application at all. But if you want to take advantage of 
rhe extended print record — and implement attractive 
features such as access to a larger number of paper 
sizes, tray handling that works w r ith the Prj<>bMerge 
function, and the ability to reliably save more user 
settings from the Page Setup dialog — you do need 
to make some minor changes, along the following 
lines: 


* Because the extended print record can be any size 
larger than 120 bytes, your application must not 
make any assumptions about the record’s size. 

* Although the locations of fields that are currently 
defined within the TPrint structure won’t change, 
you should use PrGeneral with the extended print 
record opcodes (described below) to access any 
additional fields. 

* When using an extended print record, you’ll need 
to call the extendPrDefault and extendPrValidate 
functions where you previously would have called 
the functions PrintDefault and PrVali date. (The 
new extend functions really just call PrGeneral with 
specific opcodes, but are more convenient to use 
than PrGeneral itself ) See “Extending the Print 
Record” on this issue’s CD for more information 
on the extend functions and how they use the new 
PrGeneral opcodes. 

Those who break the rules might need to make more 
changes. Sec the Print Hints column in develop Issue 26 
(“The Top 10 Printing Crimes Revisited”) for more 
information. 

NEW PRGENERAL OPCODES 

LaserWriter version 8.4 adds three new PrGeneral 
opcodes for dealing with the extended print record: 
kExtendPrintRecOp (which extends the print record), 
kGetExtendedPrintRecOp, and kSetExtendedPrintRecOp* 

' l a b 1 e 1 g i ves a co n ipi ere list of all the P rGe neral 
opcodes as of June 1996 (but be aware that printing in 
Mac OS 8 might not implement all of these). These 
opcodes are all planned to be supported by LaserWriter 
version 8.4, except for the ones that aren’t used by 
LaserWriter 8 (as noted in the table). Refer to the 
article “Meet PrGeneral” in develop Issue 3 for more 
i n formation a bout PrGen e ra I. 

NEW PRINT DIALOGS 

The print dialogs have been completely redesigned 
for LaserWriter version 8.4. Applications that use the 
approved method of extending the print dialogs will 
continue to function. But if your application uses a 
nonstandard method of extending the print dialogs, 
it’s in trouble. The definitive source about how to 
extend a print dialog is PDlog Expand, available as 
sample code on this issue’s CD and included with the 
Macintosh Technical Note “Print Dialogs: Adding 
Items” (PR 09). 


DAVE POLASCHEK (dpolasch@Qpple.com] continues to be find good wine than good been Dave works in Developer 

confused by Californio. There's nice weather when it isn't baseball Technical Support (DTS) at Apple, If you'd like more details, look 

season, the earth moves even when he's alone, and it's easier to at http://www.best.com/-davep/. * 
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Table 1. The PrGeneral opcodes 

Opcode Operation 

4 getKslDataOp 

5 setRslOp 

6 draftBitsOp 

7 noDraftBitsOp 

8 getRatnOp 

9 NoGraySct (not used by LaserWriter 8) 

10 gelPSInfoOp 

1 1 PSlntenfiansOp 

] 2 enableColorMatchingOp 

13 registerProfileOp (ColorSync 1 only; not used 

by LaserWriter 8) 

14 PSAdobeOp 

15 PSPrimaryPPDOp 

16 k Loa dCom m P rocsOp 

17 kUnloadCommProcsOp 

? 8 kExtendPrintRecGp (LaserWriter version 8,4 

and later only) 

19 kGetExtendedPrintRecOp (LaserWriter version 

8.4 and later only) 

20 kPrinterDirectOpCode (not used by any 
LaserWriter driver] 

2 1 kSetExtendedPrintRecOp (LaserWriter version 

8.4 and later only] 


The new print dialogs have a pop-ttp menu that lets the 
user select between multiple panes of the dialog. In 
Figure 1., the General pane has been selected from the 


pop-up menu. When an application adds items to the 
prim dialog, they’re added to a pane that has the name 
of the application. Because of this new multi pane 
dialog, applications that extend the print dialogs in a 
nonstandard manner will cause many problems, such as 
dialog items appearing in the wrong locations, standard 
items being overwritten within the dialog, and standard 
items being drawn incorrectly. 

Applications also shouldn’t assume that the print dialog’s 
foreground color is black or that the background color 
is white. Furthermore, when applications exit their 
CDEFs or user items, they should be careful to leave 
the foreground and background colors as they found 
them. Other items in the dialog rely on these colors, so 
if you change them the standard controls intheprint 
dialog could take on unusual colors. 

ONE-PASS PRINTING 

With LaserWriter version 8.4, when background 
printing is disabled, printing is one-pass. This means 
that there are no longer any big spool files to fill up 
your hard drive, and the first printed page comes out 
of the printer more quickly (because it doesn’t have to 
wait for the entire document to spool). The downside 
is that because die LaserWriter driver isn’t making two 
passes over the data to be printed, it might not he able 
to perform the same optimizations on the PostScript rM 
code as when background printing is enabled. As a 
result, jobs printed with background printing disabled 
might print more slowly, and in a tew cases the final 
quality could suffer. 


3.4b 1c8 


Printer: 


LaserWriter 


Destination: 


General 




Copies: 1 


Pages: ® fill 

O From: 


To: 


Paper Source: (§) fill pages from: 

O First page from: 

Remaining from: 


[ $aue Settings 


Printer 


Hu to Select 


Cassette 1256 Sheets! 


Cassette 1250 Sheets) 


3 


T 1 


[ Cance? ] f[ Print^^ 


Figure 1* The new multipane print dialog 
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With the advent of one-pass printing, if your application 
has its own PostScript LaserPrep dictionary, it should 
use the PREC 103 mechanism for this dictionary. With 
this mechanism, the driver downloads to the printer 
the PostScript dictionary contained in the PREC 103 
resource before it's needed by application-generated 
PostScript code. If the application doesn’t do this and 
defines its own PostScript procedures at the page level, 
these procedures will he undefined as part of the one- 
pass font-handling mechanism and you'll get PostScript 
errors (mostly undefined operators, because the 
operators you defined aren't there). 

PORTIONS OF THE CODE IN SHARED LIBRARIES 

Some of die functionality of LaserWriter version 8.4 
has been broken out into shared libraries, including the 
following: 

* Converter library — generation of PostScript code 

* PPD library — parsing of the PostScript printer 
description file 

* Preferences and Collection libraries — storage and 
retrieval of preferences file data 

* Down loader library — downloading of PostScript 
and EPS files to a printer 

* PostScript Utilities library —- PostScript utility 
functions 

* Communications library — communications 

In the future, Apple may provide APIs to these shared 
libraries fur third parties. 

CHANGES TO PARSING AND HANDLING OF 
PPD FILES 

If you’re a printer developer, you should know that the 
way PPD files are parsed and handled has changed in 
LaserWriter version 8.4. Previous versions of the driver 
would supply a “Printer’s Default” choice so that the 
user could choose not to decide about a certain feature 
and accept the default setting of the printer. With 
version 8.4, the driver will no longer provide this 
option. If PPD creators want to continue to have a 
Printer’s Default option for a user interface feature 
(called UI Feature in the PPD specification), they'll 
have to add it to the PPD file in the list of options for 
that feature. 

Also, common features available through the PPD file 
will be added to the correct pane of the print dialog. 


Features that aren’t recognized or that are vendor- 
specific will be placed in their own pane. This can cause 
problems: if you use a nonstandard naming convention 
for a common feature, it will be placed w ith all other 
unknown features, and if you use a standard name for 
a nonstandard feature, it will probably end up in the 
wrong location. 

One other change is that you can specify the graphic 
elements you’d like to use for UI features specified 
within the PPD file. See “LaserWriter 8.4 PPDs” on 
the CD for information about how to design your own 
pane for use w ith LaserWriter version 8.4. The latest 
Apple PPD files are the best examples of how to 
i mpIement the ncw fea tures. 

NEW ERROR CODES 

LaserWriter 8 introduced a number of new error codes, 
but they haven’t been documented —- until now, that 
is. See the unofficial documentation “LaserWriter 8 
Errors” on the CD, Future versions of this document 
will be released as Technotes. 

These error codes are provided for debugging purposes. 
Re aware that they may change in the future, so you 
probably don’t want your application to depend on them. 

WRAPPING IT UP 

Chat’s a quick rundown of the new features of the 
newest version of the LaserWriter driver. These features 
should make printing a better experience lor the user, 
should give the developer more flexibility, and should 
require no changes to most applications. And to top it 
all off, they’re cool\ 


RELATED READING 

* "Print Hints: The Top Ten Printing Crimes Revisited" 
by Dave Polaschek, develop Issue 26. 

* "Meet PrGenerof the Trap that Makes the Most of 
the Printing Manager" by Pete "Luke" Alexander, 
develop issue 3. 

* Macintosh Technical Note "Print Dialogs: Adding 
Items" (PR 09). 

* "Extending the Print Record/'"LaserWriter 8.4 
PPDs," and "LaserWriter 8 Errors/’ all on this 
issue’s CD. 


to Rich Blanchard, Paui Danbold, Ingrid Kelly Dan Lipton, 
and Steve Simon for reviewing this column. Special thanks to Matt 
Deatherage. 
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Working With OpenDoc Part Kinds 


if you're ready to create y ourfirst full-featured Open Doc part editor 
but have some questions about part kinds and how to work with them , 
you 'll find the answers here. We explain how your choke of pan kinds 
will affect whether users will be able to read your content with different 
part editors and even across different platforms. We also discuss some 
human interface principles and describe bow to handle the most common 
user actions having to do with part kinds. 



TANTEK CELIK AND 
DAVE CURBOW 


We imagine that every computer user on earth has had the experience of trying to 
open a document created by someone eke but not being able to because the 
application it was created with is missing. In the context of OpenDoc, users can run 
into this when the part editor that created a part is missing. OpenDoc provides 
several ways to mitigate this “missing editor” problem. One way is for developers to 
create and freely distribute part viewers for all the kinds of parts that they support; a 
part viewer is a subset of its corresponding editor’s code that displays and prints a 
part’s contents but can’t be used to create or edit a part. 

But suppose a user doesn’t have either an editor or a viewer for a particular part. 
That’s where part kinds come in. A pan kind is a data format in which a part’s intrinsic 
content is stored, analogous to a tile type in a traditional application. OpenDoc allows 
a part editor to support multiple part kinds — that is, to store the same content in 
multiple data formats — to increase the probability that a user will be able to see and 
copy die contents of a part. A user who doesn’t have the same part editor that created 
a part may have a different part editor that can read at least one of the data formats in 
which that part is stored. Alternatively, one or more of the data formats can perhaps 
he translated into a part ki nd for which the user has an editor or viewer. 


What this means to you is that your choice of part kinds to support is a crucial step in 
developing a part editor. This article discusses how to choose which part kinds to 
support — standard (to Macintosh or across platforms) or proprietary — and whether 


fA sn 1 K CEi !K (lantek@6prinne.com) was until 
recently an OpenDoc technical lead at Apple. 
After shipping OpenDoc 1.0 and determining that 
it was good, he helped found 6prime corporation 
(http://www.6prime.com), an OpenDoc software 
consulting firm. Tantek prides himself on his multiple 
modes of alternative transportation, including inline 
skating, bicycling, and motorcycling. He likes to 
occasionally spend time writing applications in 
HyperCard, night skating in San Francisco, or 
turning a profit shorting Microsoft options. 


DAVE CURBOW (curbow@apple.com) was until 
recently the OpenDoc human interface lead. He 
has transferred to Apple Research Labs, where 
he's working on something really neat — but he 
can't tell you about it yet. When he isn't toiling 
away at Apple or planning his next trip to Europe, 
Dave likes to work in his Japanese-style garden. 
All he needs now is a book that dearly explains 
how to twist black pines into interesting shapes. " 
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to support one or mu Id pie part kinds. We also discuss how to decide which category 
your part kinds fir into, some human interface principles having to do with part kinds, 
and what to do in a few key situations in which user actions cause your editor to have 
to deal with part kinds. 

If you're not already familiar with the GpenDoc human interface, you should first 
read “The Open Doc User Experience” in develop Issue 22 to get up to speed. This 
article also requires you to know something about Open Doc storage and how to use 
the ODStorageUnit class. "Getting Started With OpenDoc Storage” in develop Issue 
24 is a good introduction; further details can he found in the Open Doc Programmer V 
Guide for the Mac OS and its accompanying OpenDoc Class Reference CD. 

CHOOSING YOUR PART KINDS AND CATEGORY 

In developing your pan editor, you first need to decide which part kind or kinds to 
support. This choice is worthy of careful consideration, "The decision you make about 
whether to support standard vs. proprietary part kinds and how many part kinds to 
support will affect the number of users able to read your content across documents 
and platforms. Well Look at the tradeoffs here. Well also give you the information 
you need in order to decide which category or categories your part kinds fit into. 

STANDARD VS. PROPRIETARY PART KINDS 

First, you need to decide whether to support standard or proprietary part kinds, or 
some combination of each. Standard part kinds are those data formats that, either 
tlirough an official decree or by some de facto means, have become widely used and 
accepted. There are industry-standard part kinds, which are standard across more 
than tine platform, and standard Macintosh part kinds* 

Because new data formats are being created all the time, we can’t give you a complete 
list, hut here's a sample: 

* industry standards — ASCII, TIFF, GIFJPEG, MPEG 

* Macintosh standards — TEXT, PICT, stxt, MOOV, 3 DMF 

Part kinds are usually specified as ISO strings (null-terminated ASCII strings using 
7-bit characters) for manipulation by OpenDoc. As you can see from our list, standard 
Macintosh part kinds are actually today’s standard Macintosh file types, except that 
instead of being file-type signatures they're ISO strings, which can he derived by 
using methods of the class ODTfanslation. (See the Data Interchange recipes on the 
OpenDoc Class Reference CD for more details on how to properly support a standard 
Macintosh part kind based on a standard Macintosh file type.) Your part editor needs 
to provide user-readable names for parr kinds in a name-mapping resource; more on 
this later. 

rhe ASCI! star d< a* ■ lly pretty loosely defined. It doesn't specify whether 
you should use 7- or 8-bit encoding, nor does it say whether you should use LF, CR, or 
CRLF for line separators. In the near future, Unicode, which OpenDoc uses internally 
is likely to become the standard. In the meantime, your part may need to be prepared 
to handle several variants on the ASCII standard without failure.' 


If the part kind you choose to support is an industry standard, users wall benefit 
because they'll be more likely to avoid die missing editor problem mentioned earlier* 
Furthermore, supporting standard part kinds enables your part editor to support 
more of the content that’s already out there* Let’s face it — data formats don't live 
forever, but the standard ones have a much better chance of being long-lived than any 
p r o pr i eta ry ki n d s you ere a te. 
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On the other hand, if there's no standard for the content your part editor creates, or if 
the standard won't suffice to capture the functionality your part editor offers, you'll 
need to create a proprietary part kind. You must weigh the advantages of using a 
proprietary part kind against the disadvantage of users possibly not being able to read 
your part's content. 

In any ease, don't redefine an existing standard. For example, the TEXT part kind 
should he used only for plain text, not for some data format that uses text as part of its 
definition, such as PostScript, HTML, or BinHex. These data formats should be part 
kinds in their own right. Otherwise, there will be confusion when OpenDoc needs to 
find a substitute part ediror for a part that claims to be TEXT but is in fact another 
kind such as HTML. The user won't he happy wurh the result. 

If you decide to use an industry-standard part kind, the Bento container suite (part 
of the storage system in OpenDoc 1,0) can help you solve internal byte-ordering 
problems and ensure that a document written on any OpenDoc platform can be read 
and written on any other OpenDoc platform. Flow ever, your part editor is responsible 
for proper byte ordering of the values in the content property 1 of your storage unit, 
(Data formats typically specify byte ordering, so OpenDoc stays out of your way 
here.) The Standard Type I/O utilities (see the file StdTypIO.h and the functions 
declared there) solve the byte-ordering problem for a variety of simple data formats. 
These utilities can be used in combination to build up more complex data formats. 

SUPPORTING MULTIPLE PART KINDS 

As weVe said, your editor can support one or more part kinds. If it supports more than 
one part kind, one of these will be the preferred kind . Users implicitly indicate the 
preferred kind when they choose a stationery pad or cut and paste content. They can 
also change the preferred kind in the Part Info dialog if they desire; more on this later. 

Supporting multiple part kinds increases the probability that other users can see the 
contents of a part created widi your editor, even if they don't have your part editor 
(see “Editor Substitution Explained” for why this is so). Your choice of part kinds to 
support comes into play both when the user saves a document with parts created by 
your editor and when the user transfers data with a paste or drop operation. 

When deciding how many part kinds to support when your editor is saving its parts 
of a document, you’ll want to consider the tradeoff between portability and the space 
required to store your part as multiple kinds* The most transportable part kind (that 
is, the standard one) may not be the most compact or the one that will represent the 
underlying contents with the greatest fidelity. Typically, you'll want to store only the 
one preferred part kind, or the preferred kind and one standard part kind. If there isn't 
a standard kind that's roughly equivalent to your preferred kind, consider also storing 
a TEXT or PICT representation, simply to maximize the chances that the user will 
be able to see something for your part. For example, if your part’s preferred kind is 
IDMFi there isn't an equivalent standard kind, so you should also store a PICT 
representation. You might want to present the user with a Settings or Preferences 
dialog giving a choice of part kinds to store in addition to the preferred kind. See 
pages 476 and 479 of the OpenDoc Programmer's Guide for implementation details. 

When your editor is proriding data for a data transfer operation (such as a copy to 
the Clipboard), you may w^ant to write out a greater number of standard part kinds 
than during a save operation. This is because during data transfer it's more likely that 
the user is trying to move content to a different editor or application. Providing 
standard part kinds in this situation is therefore even more important. On the other 
hand, remember that the user can use the Paste As command to get more options, 
including translation, so you needn't go overboard in supporting lots of kinds. 
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EDITOR SUBSTITUTION EXPLAINED 

When a user fries to open a document or edit a part and 
the editor that created it is missing, OpenDoc searches for 
a substitute. This occurs as part oF Open Doc's binding 
process — the process of assigning the correct part editor 
to a given part. When a document is opened, the 
OpenDoc binding subsystem binds editors to all parts that 
need to be displayed. During execution, OpenDoc binds 
editors to part data when a part is read in or when its 
editor is explicitly changed. 

Let's look at a simplified example of editor substitution. 
Suppose we've created a text editor named SurfWriter 
that stores its content in three formats; a proprietary part 
kind [SurfWriter Text) and two standard port kinds (RTF 
and TEXT), And suppose that SurfWriter Text is the 
preferred kind. When OpenDoc tries to display the part, 
its binding subsystem looks first for SurfWriter — the last 
editor that was used. If that isn't Found, the binding 
subsystem looks for an editor that can read SurfWriter 
Text — the preferred kind, if that can't be found, it looks 
for one that can read RTF or TEXT. Thus, storing multiple 
part kinds increases the probability that users will be able 
to read your content with different part editors and across 
different platforms. 

Now let's look at editor substitution in a little more detail. 
When attempting to find an editor to bind to a part, 
OpenDoc looks first for the editor that last edited the part, 
specified in the kODPropPreferredEditor property in the 


part's storage unit. If this editor isn't present on the user's 
system, the binding subsystem examines each of the part 
kinds in the stored part and the list of kinds supported by 
the editor or editors installed on the user's system, looking 
for a match. For each supported kind, there's a default 
editor. The user can inspect and modify the list of default 
editors in the Editor Setup control panel (Figure 1). 

During the matching process, the binding subsystem looks 
first for the default editor for the preferred kind. If this 
editor isn't present, it looks for the default editor for the 
preferred kind's category, and finally for any editor that 
can read the preferred kind. If such an editor can't be 
found, the binding subsystem repeats the whole process 
for each of the remaining part kinds in the part, from 
highest fidelity to lowest. 

If no editor for any of the part kinds is installed on the 
user's machine, the part remains unviewable and 
unedifable. But OpenDoc still binds an editor to the part 
— the "editor of last resort." This editor is always 
available and represents the part as an icon within the 
document, so that there's never a blank spot in the 
document where a part can't be displayed. The user can 
examine the part's kind in the Part Info dialog, which 
gives a clue as to which editor or viewer should be 
installed, although if there's no editor for the part, there's 
probably no user string for the preferred kind. The user 
can also decide to translate the part to another part kind. 
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Figure 1 . The Editor Setup control panel 
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CATEGORY CONSIDERATIONS 

After you’ve chosen the part kinds to support, you need to determine which category 
or categories these belong to, A part category is a set of part kinds that are conceptually 
similar. You might think of it as a generic term for several “brand name” variants. For 
example, the kOD Category StyledText category might include the part kinds SurfWriter 
Text 3,0, SurfWriter Text 2,0, and others, 

OpenDoc looks at a part’s category to decide which pari editors or part viewers can 
he substituted if an editor is missing and whether to merge or embed data when 
content is copied from one part into another. Categories are specified by your editor 
in a name-mapping resource and can’t be changed by the user. 

Categories for existing part kinds have already been determined and should be 
adhered to; this set of categories is broad enough to include most new part kinds as 
well. A list of the predefined categories is given In Table 1. This list can be found in 
the OpenDoc Programmer's Guide on pages 477-478, but note that a new category has 
been added since the publication of the book: kODCategoryArchive. 

The majority of the entries in the list (such as kODCategoryPlainText and 
kODCategoryStyledText) are self-explanatory, but a few need some clarification. 


Table 1 , Predefined pari categories 

Part category 

kO DC ategory PI a i nText 
kO DC ategory StyledText 
kO DC ategory Draw t ng 
kO DC ategory 3 DG ra p h ic 
kO DC ategory Pa i n H ng 
kQDCategoryMovie 
kODC ategory So m p led Soun d 
kODC a tegary StructuredSou nd 
kODCa tegoryC hart 
kODCa teg o ry F a r m u la 
kODCateg o ry S p read sheet 
kODCa teg o ryToble 
k ODCa teg o ry D ata base 
kODCa teg o ry Q uery 
kODCa teg a r yCon nect i on 
kODCa teg o rySc r i pt 
kO DCa leg a ryO utt i ne 
kODCa teg ary Pag elayout 
kO DCa teg ary Presentati on 
kO DCa teg oryCd en da r 
kO DCa teg ary Form 
kO DCategory Executable 
kO D CategoryCom pressed 
kODCategoryControJPa nel 
kO D C ategoryC o n trol 
kO DC ategory Perso na f I n fo 
kO DC ategory Space 
kO DC ategory Pro feet 
kQDCategorySig nature 
kODC ategory Key 
kO DC ategoryUtility 
kO DC ategoryMa i I i n g La be! 
kODCategoryLacator 
kO DC ategory P ft n ter 
kO DC atego ryTi me 
kO DC ategory Arch ive 


Explanation 

Plain ASCII text 
Styled text 

Object-based graphics 

3D object-based graphics 

Pixel-based graphics 

Movies or animations 

Simple sampled sounds 

Sampled sounds with additional information 

Chart data 

Formula or equation data 
Spreadsheet data 
Tabular data 
Database information 
Stored database queries 
Network-connection information 
User scripts 

Outlines created by an outliner program 
Page layouts 

Slide shows or other presentations 
Calendar data 

Forms created by a forms generator 

Stored executable code 

Compressed data 

Data stored by a control panel 

Data stored by a control, such as a button 

Data stored by a personal information manager 

Stored server, disk, or subdirectory data 

Project-management data 

Digital signatures 

Passwords or keys 

Data stored by a utility function 

Mailing labels 

Locators or addresses, such as URLs 
Stared printer data 
Stored dock data 

Archive or partial archive data such as TAR 
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* kOD Cate gory Outline —- Use this category when your part’s content has 
some hierarchy — that is, when the content is assigned to different nested 
levels. For example, the Cyberdog Notebook, an excerpt from which is 
shown in Figure 2, presents a collection of URLs in hierarchical form and 
thus is an outline. 

* kODCategorySpace — Use this category when the content has no intrinsic 
order, as in the case of server, disk, or subdirectory (folder) data. For 
example, in a pre-System 7 Finder folder, the order of the contents depends 
entirely on the settings of the View menu. A part with content like this 
would belong to this category. 

* kODCategoryPersonallnfo — Use this category for die various kinds of 
information represented in personal information management (PIM) 
applications. 

* kODCategoryPageLayout — Use this instead of kODCate gory Drawing 
when die part contains only embedded content. In contrast, the category 
kODCategoryDrawing is for a drawing that has intrinsic content, such as 
circles and rectangles. 



Figure 2* Example of an outline From the Cyberdog Notebook 


Some of the categories seem as though they could be subsets of other categories — 
for instance, kODCategoryP1 ainText could be a subset of kOl) Care gory Sty ledText, 
anil kODCategory3D Graphic could he a subset of kODCategory Drawing. But 
categories aren’t hierarchical — that is, one category can’t Include others. 

When you’re considering which category or categories your pan kinds should belong 
to, ask yourself the following question for each of the categories: I fusers pasted my 
kind of data into a part belonging to rhis category, would they expect the content to 
be merged, or embedded as a separate part? If they would expect the content to be 
merged, that’s a category your part kind should belong to. (Note that whether a part 
kind supports embedding doesn’t affect which category it’s in.) 

For example, if users pasted a slide (a part belonging to the kODCategoryPresentation 
category) into some text (a part belonging to the kO D Cate gory StyledText category), 
they would expect the slide to be embedded within the text because the operations on 
slides and text are very different. But if they pasted one slide into another slide, they 
would expect the contents of the first slide to be merged into the destination slide; 
thus, the two parts should belong to the same category. 

Consider anodier example. If users pasted a picture from a Web page into a part 
belonging to the category kODCategoryPainting, they would probably expect it 
to be merged. But if diey pasted the picture into a part belonging to the category 
kODCategoryDrawing or kO D Category 3 DGra phi l\ they would probably expect it 
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to be embedded, because the operations available in a painting part are usually very 
different from those in a drawing part. Thus, the picture should belong to the 
cate go ry kO D C ia tc gory Pa i nti ng. 

You need to choose one or more categories for each of die parr kinds that your part 
editor supports. A part kind can be in multiple categories; for example, a part that can 
shift its view from table to chart should have a preferred kind that’s a member of both 
categories* The same category can he specified for a part kind that represents a single 
object and a part kind that represents a collection of those objects; for example, you 
can specify kODCategoryDatabase for a part kind that represents a single database 
record and for a part kind that represents a collection of such records. 

As mentioned earlier, when your part editor provides content to the Clipboard or a 
drag and drop object, you may want to write out a greater number of standard part 
kinds than during a save operation, to increase the probability of being able to 
interchange data with other parts. In fact, it will help if you support kinds in more 
than one category* Here’s an example: Suppose a user copies some spreadsheet cells 
and pastes them into a chart. Because the operations on cells and charts are different, 
the user wi 11 expect the spreadsheet cells to be embedded. However, if the spreadsheet 
provides its copied data in a format that the chart is prepared to merge, the user gets 
a higher level of interoperability* If the spreadsheet and the chart both support kinds 
that are in the kODCategoryPlainText category, for instance, the chart can take the 
content of the spreadsheet and chart it instead of embedding the spreadsheet. 

Here are some more examples of part kinds and the categories they fit into: 

* PostScript — This page description language is used to define images 
in a structured fashion. The PostScript format might fit into cither 
kODCategoryPageLayout or kODCategoryDrawing, We recommend 
kODCategory Drawing because a part in PostScript format has intrinsic 
content like a drawing, such as arcs and clip shapes. 

* HTML — Hypertext Markup Language (HTML) is similar to PostScript in 
that it defines a page layout. However, when HTML is displayed it typically 
looks more like styled text than like a drawing. Therefore, the appropriate 
category for HTML is kODCategoryStyledText* 

* BinHex — I ike many other formats that claim to be text but are only 
making use of text to define some richer format, BinHex is actually an 
archive format* Hence BinHex belongs in kODCategory Archive* 

* URL — Another kind that uses text to define some richer format, a URL 
should be in kODCategoryLocator. 

If your part kinds don’t appear to fit in any of the predefined categories, you can 
request a new category. The list of predefined categories is maintained by Cl Labs, a 
consortium that coordinates cross-platform OpenDoc development* See the Cl Labs 
Web page http://www.dlahs.org/categories for instructions on how to request a new 
category. 

RESOURCES REQUIRED 

Both part kinds and part categories are assigned in your part editor’s name-mapping 
fnmap’) resources* You can learn how to construct these resources by looking at the 
Dynamic Binding recipes on the OpenDoc Class Reference CD. These resources are 
required: 

* EdkorKinds — lists every part kind your editor supports, except standard 
Macintosh part kinds 
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* EditorPlatfomiKind — lists the standard Macintosh part kinds your editor 
supports 

* KindCategories — lists the category or categories your part kinds belong to 

* KindUserString — lists the part kind user strings 

If you request a new category and Cl Labs approves your request, you'll also need a 
CategoryUserString resource listing your category user strings. Open Doc already 
contains user strings for predefined categories. 

Listing 1 shows an EditorPlatfomiKind resource indicating that your editor supports 
TEXT files and TEXT scrap data. Listing 2 demonstrates how a part editor would 
declare two part kinds that are in the same category in a KindCategories resource. 

At run time, if you need to convert a Mac OS file type such as 'TEXT' to an ISO 
type, first get the translation object from die session: 

QDTranslation* translation = session->GetTranslation(ev); 

Then call the translation object to convert the Mac OS file type, or what we call the 
platform kind (a platform*neutral term), to an ISO type: 

ODVaiueType valueType = 

translation->GetISOTypeFromPlatformType ( 1 TEXT 1 , kODPlatformFileType); 


Listing 1. An example EditorPlatformKmd resource 

resource kODNameHappings (kPlatformEditorKindMapId) 

{ 

kODEditorPlatformKind, 

{ /* array KeyList: 1 element */ 

/* ( 1 ] */ 
kYourEditorlD, 
kODIsP11fmType Spa c 

{ /* array FltfmTypeSpacList: 2 elements */ 

{ 

/* [ 1 ] */ 

kODPlatformFileType, 

'TEXT * t 
smRoman, 
langEnglish, 

"Plain Text", 
kODCategoryPlainText, 

/* [ 2 ] */ 

kODPlatf omDataType, 

'TEXT', 

smRoman, 

langEnglish, 

"Plain Text", 
kODCategoryPlainText, 

> 

} 

> 
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Listing 2* An example KEndCategories resource 


resource kODMameMappings (kKindCategoryMapId) 

{ 

kODKind, 

{ /* array kinds: 2 elements */ 

/* til */ 
kStyledTextKindl, 
kODIsMISOS tr ingLis t 
{ 

{ /* array categories: 1 element */ 

/* [ 1 ] */ 

kODC at e go ryS ty1edTex t 

> 

b 

h [2] */ 

kStyledTextKind2, 
kODI sAn ISOStringLi at 
{ 

{ /* array categories: 1 element */ 

f* [ 1 ] */ 

kODC ate goryS ty1edT ext 


} 


}? 


} 


} 


You’ll find kODPIatformFileType defined in StdDcfs.xh, ODTransIarion defined in 
XranslLxh, and ODSession defined in ODSessnjdn Use kODPlatfbrmDataType 
instead of kODPlarformFiieType if you’re converting a scrap type from the Clipboard 
as opposed to a file type from the file system. 


SOME HUMAN INTERFACE PRINCIPLES 

There are some important human interface principles regarding part kinds that you 
should incorporate in the design of your part editor. They boil down to maintaining 
the fidelity of parrs as they pass through various operations. 

One key principle of the user model is that editors shouldn’t change the part kind of 
content without warning, because the translation may cause information to be lost. 
Only the user should he able to change the preferred kind of a part, and then only 
through an explicit action. This supports the concept that content copied into or out 
of an Open Doc document should retain its fidelity. For example, when the user drags 
a drawing document from the desktop into an Open Doc document and then back to 
the desktop, the initial document and the final document should be identical, as far as 
the user is concerned. The final document should have the same part kind as the 
original document, unless the user elects to change the part kind. (See the recipe for 
promising a non-Open Doc file on the Open Doc Class Reference CD for more details.) 

Users can change the preferred kind of a part with the Part Info (or Document Info) 
command in die Edit menu. This command brings up a dialog like the one shown in 
Figure 3. A pop-up menu offers a list of part kinds supported by the current editor, 
plus the possibility of translating to a different format with the 'Translate to” 
command. 
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Part Info 


Name: 



Frame ▼ | 

□ Bundled 

Styled Text 

SurfWriter Text 



SurfWriter 1.2 



Size: 2Q2K on disk 

Created: Wed, Jan 1 7, 1996, 5:3a PM 
Modified: Fri, Jan 1 9, 1 996, 6:03 PM 
By: Dave Cur bow 
ID: 38 


[ Settings,,, 


[ Cancel ] | OK j| 


Figure 3* The Part Info dialog 

When the user wants to save a document, your editor should write it out in the format 
of the preferred kind. The highest-fidelity kind that your editor writes should be die 
preferred kind. Don't change the preferred kind, because that would be implicit 
translation, or translating formats behind the user’s back — not a good idea, although 
some applications behave this way today. Perhaps you’ve seen this: the application 
claims to read or write a particular data format, but when a document of that file type 
is opened with that application and then saved, the application converts the document 
to its own proprietary format. Users are left wondering why their documents can’t 
stick with the format they were created with. 

to maximize interchange between OpenDoc, traditional applications, and system 
software, OpenDoc does not arbitrarily promote platform kinds (which, remember, is 
our platform-neutral term for Mac OS file types] to OpenDoc part kinds. 

In today’s applications, this unexpected format change is also often associated wdth the 
creation of a new document named “Untitled x* or “FooDoeumenc - converted.” In 
OpenDoc, parts don't have control over the name of the document, so this errant 
behavior is prevented. The name of the document, just like the preferred kind of a 
part, should be considered a user setting. Editors shouldn't tamper with user settings. 

There are situations wdiere it’s appropriate for the editor to query the user about 
changing a part kind. If die user tries some operation, or tries to add some content, 
that's not supported in the current kind but is supported in another kind that the editor 
understands, it’s appropriate to suggest changing to the kind with more functionality. 

As an example of the first situation, suppose the user is editing a plain-text document 
with an editor that supports styled text. If the user selects some text and tries to 
change it to bold, the part editor must allow this change but should warn the user 
that the operation will require a change in the part kind — and the user must he 
allowed to veto this operation before it’s done. In this situation the part editor should 
display an alert like the one shovm in Figure 4. 





































“Plain Tent” does not support this operation. 
Do you LLiant to change this part’s kind to 
“Styled Tent,” which does support this 
operation? 


[ Cancel j |change* J 


Figure 4, Warning the user that an operation requires the part kind to be changed 

As an example of the second situation, suppose the user now pastes some text that 
includes a page break and an indentation, which isn't supported in styled text but is 
supported in a proprietary format the part editor uses. The part editor should allow' 
this change hut present an alert (see Figure 5) and let the user veto die change* 


“Styled Teat” does not support this kind of 
/! \ content. Do you want to change this part’s 

kind to "SurfWriter Teat,” which does support 
this kind of content? 


[ Cancel J 


[[change || 


Figure 5, Warning the user that adding content requires the part kind to be changed 

HANDLING USER ACTIONS 

A number of user actions require your editor to deal with part kinds and categories, 
though in most cases this interaction is transparent to the user. For example, when a 
user pastes content into a part, the editor of the parr where the content is about to be 
pasted examines the part kinds and categories of the content being pasted* The editor 
decides which, if any, of the multiple part kinds available will be pasted* In this case, 
as in many others, the user doesn't realize what’s going on behind the scenes with part 
kinds and categories* 

We'll discuss in detail what your editor should do with part kinds and categories in 
response to each of the following user actions: 

* creating a document 

* opening a document 

* saving a document 

* transferring data 

* changing the preferred kind 

* translating or converting a part 

CREATING A DOCUMENT 

To create a document, the user double-clicks on a stationery pad that you supply with 
your part editor. You must provide at least one stationery pad for each part category 
that your editor supports* For example, if your editor supports the “styled text” 


WORKING WITH OPEN DOC PART KINDS 


47 































category and the SurfWriter Text, Acme Writer Text, and RTF part kinds, you must 
supply (and your product’s installer must install on the user’s system) a stationery pad 
for at feast one of these part kinds, Typically, you’ll install a stationery pad for the 
highest-fidelity part kind that you support. 

You can optionally provide more than one stationery pad. When users decide to 
double-click on one stationery pad instead of another, they’ve made an explicit 
decision about the preferred kind of the document they want to be created. 

Rules and conventions for installing part editors and stationery pads can be found in 
the OpenDoc Programmer's Guide , Appendix C, “Installing GpenDoc Software and 
Parts,” 

OPENING A DOCUMENT 

Whenever a user opens a document containing one of your parts, your pan must be 
reconstituted from external storage by your InitPartFromStorage method, described 
in detail in the article “Getting Started With OpenDoc Storage” in develop Issue 24, 
Your editor needs to find out the preferred kind and read in the content data 
accordingly. 

If your editor supports any platform kinds (Mac OS file types), you should first check 
for the HFSFlavor value type in the content property (kODPropContents) of the 
part’s storage unit. If it’s there, you’ve been bound to an empty storage unit that’s 
pointing to a file that you should use to internalize from. This binding can happen in 
one of two ways: the user may have dragged and dropped a traditional Macintosh file 
onto an OpenDoc document and your part editor was bound to the drop, or the user 
may have opened a traditional Macintosh file with the OpenDoc launcher application. 
For detailed information on how to make this work, see the Drag and Drop Recipes 
on the OpenDoc Class Reference CD, specifically the section “Incorporating Data From 
a Non-Open Doc Document.” Also, see the section “Accepting Non-OpenDoe Data” 
on page 371 of die Ope??Doc Programmer's Guide. 

If your editor doesn’t support any platform kinds, follow these steps: 

L Get the preferred kind — that is, read the value from the kODPropPreferredKind 
property of the part’s storage unit. If this property doesn’t exist, the editor can 
assume that the preferred kind of the part is the value type of the first value 
in the content property. Keep the preferred kind in a field, as shown in the 
following example using utility functions from StdTypIO and TempObj: 

#include <5tdTypI0.h> 

#include <TempGbj.h> 

// The following code belongs in your InitPartFromStorage method. 
ODStorageUnit* su = self->GetStorageUnit(ev ); 

TempISOStr preferredKind = ODGetISOStrProp(ev # su f kODPropPreferredKind, 
kODISOStr, kODNULL); 
if (preferredKind == kODNULL) { 

su->Focus(ev, kODPropContents, kODFosUndefined, kODNULL, 1, 
kODPosUndefined); 
preferredKind = 3u->GetType(ev); 

} 

2. Focus your part’s storage unit to the value of the content property whose 
value type is die preferred kind. 

self->GetStorageUnit{ev)->Focus(ev, kODPropContents # kODPosUndefined, 
preferredKind, 0, kODPosUndefined); 
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3. Read the contents of that value and create die in-memory data structures 
necessary to represent that content. Use the ODStorageUnit method 
GetVahie to accomplish this step. 

Note that ids possible for your editor to be bound to a part that previously had a 
different editor, as described earlier in “Editor Substitution Explained,” In this case, 
the Open Doc binding subsystem will automatically notify die user. If your editor 
doesn't support the preferred kind, use the highest-fidelity kind in the content 
property that your editor does support as the de facto preferred kind. Do not update 
the preferred kind property until Externalize or ChangeKJnd is called on your part. 

SAVING A DOCUMENT 

Whenever a user saves the document, your part must be written out to die storage 
unit, or externalized, by your Externalize method, described in detail in the article 
“Getting Started With Open Due Storage” in develop Issue 24. Your editor should 
write out the preferred kind, at a minimum; you may also decide to write out one 
or more alternate part kinds, as discussed earlier under “Supporting Multiple Part 
Kinds.” 

The first two steps that are required have to do with preparing the storage unit for 
clean extemalization from your part editor, also known as “prepping the storage 
unit,” You should only have to do this the first dme Externalize is called on your 
part, 

1. Clean up the storage unit by removing any values that you won't be 
updating. This means calling the Remove method for any values in die 
content property diat have value types (part kinds) that your editor doesn't 
support or that your editor won't externalize, 

2. Add values if necessary. Use Add Value to create or recreate the value types 
drat you want to externalize in proper fidelity order (from highest fidelity to 
lowest fidelity). Fidelity ordering is important because OpenDoc looks at it 
to determine which editor would best edit any given part* 

3, Externalize your content in the format of the preferred kind that your editor 
kept track of in a local field. 

4, Optionally write out alternative part kinds. As mentioned earlier, the typical 
part editor should by default write out only the one preferred kind, or the 
preferred kind and one standard part kind. If you present users with a 
Settings or Preferences dialog to indicate a set of alternative part kinds to 
store, write out the alternative kinds indicated there. 

Your Externalize method may be called at times other than w hen the user saves a 
document. For example, depending on the Save model of the current document and 
the idle-time optimizations that may or may not be present, your part may be told to 
externalize only when the user saves a document or as often as every minute* 
Therefore, your editor shouldn't have preconceived notions about why it's asked to 
write out your part. As an optimization, your editor should keep an fDirty flag that's 
set whenever the user changes the part's content and cleared whenever extemalization 
is completed. If your fDirty flag is dear, your Externalize method should be a no-op, 

TRANSFERRING DATA 

Whenever the user transfers data with Cut, Copy, Paste, Paste As, or drag and drop, 
your Clonelnto method is called. See the section “The Cloneln to Method of Your 
Part Editor” on pages 327-329 of the OpenDoc Programmer's Guide for the precise 
details of implementing the Clonelnto method. 
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For the purposes of multiple part kind support, however, your editor should do the 
following: 

1. Write die same part kinds you would if you were externalizing, plus any 
standard part kinds you support. As explained earlier, it's more important to 
write out standard part kinds during Clonelnto than Externalize because the 
user is more likely to be trying to move eontent to a different editor or 
application. 

2. Call SetPromiseValue for each part kind if you’re using promises (explained 
in the Open Doc Programmer's Guide), 

If your pan editor is a container, ids important for it to treat pasted content 
appropriately. When your container receives a PasEe command or is the destination 
of a drag and drop, it should check the preferred kind of the incoming content to 
decide whether to merge or embed that content. If the category of the preferred kind 
of the incoming content is the same as the category of your content's kind, merge the 
incoming content; otherwise, embed the incoming content into a new part. 

As mentioned earlier, it's possible for kinds to belong to more than one category. If 
the incoming content's kind or your content's kind belongs to multiple categories, or 
if both do, as long as they share at least one category they can be said to be of the 
same category. If the incoming content isn’t an OpenDoc part, simply use die data 
type that's closest to your own content kind as the de facto preferred kind for the 
incoming content. 

If the user drops a part onto your part that you determine should be merged, and you 
find diere's no content when you try to merge it, the operation will appear to be a 
no-op, which is very confusing to the user. You may want to actually embed an empty 
part in this case rather than merging nothing, so that the user at least receives some 
feedback. 

You also should be aware of a concern about format fidelity that arises if the user 
attempts a paste or drop operation with your editor thar involves content with other 
content embedded. Some data or formatting may be lost if one or more of the part 
kinds supported by your part editor is of lesser fidelity and can't handle embedded 
content, and at die time of the paste or drop the destination part editor can work only 
with the lower-fidelity kind. In this case, the destination part editor can’t know that 
it's losing the embedded content. 

What can you do to minimize these eases, or at least make them easier on the user? 
We strongly recommend that your part editor support embedding. If it doesn’t, it 
shouldn't claim to support a kind that includes embedding. For example, the part 
editor that's the destination for a paste or drop shouldn’t strip embedded content or 
links out of the data format. If your editor can't preserve the fidelity of the paste or 
drop, it must choose a lower-fidelity part kind; if there are no other kinds present 
that your editor supports, it shouldn’t allow the paste or accept the drop. The only 
exception to this is when a plain-text editor receives a paste of styled text; in this case, 
it can use only the text and ignore the style information. Because text is so ubiquitous, 
it's handled differently from other kinds of content. 

If your port editor supports embedding, it should allow the user to embed 

any content that coni be merged; \\ shouldn't restrict the kinds that can be embedded. * 

Remember that if your part editor supports data interchange, it must completely 
support Undo, so that if data or formatting is lost in a transfer operation, the user 
can undo and recover what was lost. Although most of today's applications don't alert 
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the user when data or formatting is lost, users seem to recognize with ease when 
they’ve experienced such a toss and need to choose Undo to recover. With the 
multiple-level Undo support in OpenDoc, recovering from a loss of data or formatting 
is much easier. 

CHANGING THE PREFERRED KIND 

Whenever die user changes the preferred kind of a part, your ChangeKind method 
is called. This is usually done from the Part Info (or Document Info) dialog shown 
earlier, but you shouldn’t assume that that will be the only user interface that can 
cause this method to be called. 

Your editor should do the following: 

1. Externalize the part in the new preferred data format. Make sure that die 
fidelity order of the values in your content property is maintained by 
creating the values for the supported part kinds in the right order. You may 
need to prep your storage unit again and recreate the values to ensure that 
they’re in die proper fidelity order. Ids up to your part editor whether you 
keep the previous preferred kind or not. 

2. Write the new preferred kind into the preferred kind property of the part, as 
shown in the following example using utility functions from StdTypIG and 
TempObj: 

#include <StdTypIO.h> 

#include <TempObj.h> 

// The following code belongs in your ChangeKind method; the kind 
// that the user selected is passed in the ChangeKind parameter* 
ODStorageUnit* su = self->GetStorageUnitfev}; 

ODSetISGStrProp(ev, su r kODPropPreferredKind, kODISOStr, ChangeKind); 

TRANSLATING OR CONVERTING A PART 

The user can force translation of a part with the Part Info (or Document Info) 
command in the Edit menu, which brings up a dialog like the one shown earlier in 
Figure 3. The part kind pop-up menu in the dialog, in addition to listing part kinds 
supported by the current editor, offers the possibility of choosing “Translate to” and 
then choosing a part kind from the Translate To dialog. The part kind pop-up menu 
shown in Figure 6 illustrates a number of different ways that picture data can be 
stored on the Macintosh, including standard MIME types, standard Macintosh file 
types, and standard Macintosh data types. Of course, most part editors won’t support 
this many different kinds. 


Kind 


* PICT data 
image/x-pict 
i mage/j peg 
i mage/gif 
image /tiff 
PICT file 
JPEG file 
JPEG data 
GIFf file 
GIFf data 
TIFF file 
TI FF data 
Translate to .., 


Figure 6. The part kind pop-up menu 


WORKING WITH OPENDOC PART KINDS 


51 







There are also data interchange utilities, such as converters and grinders, that convert 
parts or entire documents to different part kinds* This operation involves asking each 
part in the original document to externalize itself in a set of standard part kinds* The 
user may initiate this action by dropping a document on a converter or grinder icon 
(like the one shown in Figure 7) on the desktop* Your ExtemalizeKinds method is 
called in response. 



Figure 7. A converter icon 

ExtemalizeKinds is passed a list of kinds to externalize* Your part editor doesn't need 
to write other values it might ordinarily write in addition to the preferred kind. Your 
editor should do the following in its ExtemalizeKinds method: 

1. Externalize the set of part kinds specified* Make sure that rhe fidelity order 
of the values in your content property is maintained by creating the values 
for these part kinds in the right order* You may need to prep your storage 
unit again and recreate the values to ensure that the/re in the proper fidelity 
order. Be sure to write out these kinds in addition to the preferred kind, not 
instead of the preferred kind. 

2. Ignore any part kinds in the set that you don’t support. 

PARTING WORDS 

By now you should have a good idea of all the ramifications of choosing the part 
kinds to support with your part editor. We hope that by spelling out what the 
tradeoffs are and suggesting how your part editor should respond to various user 
actions related to part kinds, we Ye helping to promote a consistent approach to 
working with part kinds. This is bound to result in more portable parts and happier 
users* 


RELATED READING 

* OpenDoc Programmer's Guide for the Mac OS by 
Apple Computer, Inc, (Addison-Wesley, 1995). This 
book is accompanied by the OpenDoc Class Reference 
CD and includes the OpenDoc human interface 
guidelines. 

* OpenDoc Cookbook for the Mac OS by Apple 
Computer, Inc. (Addison-Wesley, 1995). 

* "The OpenDoc User Experience" by Dove Curbow 
and Elizabeth Dykstra-Erickson, develop Issue 22, 


* "Getting Started With OpenDoc Storage" by Vincent 
Lo, develop Issue 24, 

* Byte Guide to OpenDoc by Andrew Mac Bride and 
Joshua Susser (Osborne McGraw-Hill, 1996), 
http:/ / w ww. spl a s h. n et/ book s/ a pe ndoc. 

* The OpenDoc World Wide Web pages, Apple's page 
is at http://www.opendoc.apple.com, and the Cl Labs 
page is at http://wwwxilabs,org/opendoc.htmt. These 
include updated recipes, technical notes, and the like. 
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Using Apple Guide 2.1 With OpenDoc 



PETER COMMONS 


You've helped create an Apple Guide guide for your standalone 
application. Now your company is writing an OpenDoc part editor, but 
it's not obvious how Apple Guide can be used in the context of pans and 
compound documents. The answer is Apple Guide 2.1, which extends 
the original version to allow easy use of Apple Guide features, including 
Help menu management, coachmarks, and context checks, in the world 
of OpenDoc. This article introduces the new features of Apple Guide 
2.1 and explains in detail how to use them with OpenDoc. 


The world of OpenDoc isn’t like the world of the standalone “behemoth” application 
— a fact that hasn’t escaped the notice of developers who want to provide online 
help. An application developer can easily provide complete online help since the 
application is a single self-contained unit that will run in its own window. On the 
other hand, the developer of an OpenDoc pan editor never knows what other part 
editors will be running along with it during an OpenDoc session. Users can have any 
number of part editors running in any number of windows at the same time. All the 
editors might belong to a package written by one company, or, more likely, it might 
be a conglomeration w r ritten by a number of different companies. Under these 
circumstances, providing help gets a little more complicated. 

Since Apple Guide is such a powerful help system, wouldn’t it be nice if it could be 
applied to the new r world of OpenDoc? Enter Apple Guide 2.1 (released right on the 
heels of Cyberdog, Apple's new r integrated suite of OpenDoc part editors for the 
Internet). The raison d'etre of Apple Guide 2.1 is to support Apple Guide for OpenDoc, 
with particular emphasis on Cyberdog, This version includes a number of new 
fea tures, some of which are specific to OpenDoc and some of which aren’t Among 
these new features are the following: 

* a combined Full Access w indow (known as a Merged Access window) that 
contains all the guide topic areas and index terms tor OpenDoc part editors 
currently running 

* a similar ability to merge guides in conventional applications 

* the ability to specify a list of applications for which a particular guide is 
intended 

* support for a whole new' series of OpenDoc-re I a ted context checks 


PE?ER COMMONS (commons@guideworb.comj 
is the vice president of engineering at guide Works, 
LLC. He lives happily with his wife, Claire, their 
dog, Chet, and their cats, "fat cat" Clyde and 


"brat cat" Oliver, In Sunnyvale, California, and 
wonders if hell ever finish writing updates to 
Spaceward Hoi * 
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In this article, I’ll describe how Apple Guide behavior has changed in the world of 
OpenDoc, and Fll a!so tell you about some new features of Apple Guide 2.1 that you 
can use in conventional applications. Til go over the simple steps you must take to add 
a guide to an OpenDoc part editor, and then I’ll cover some of the things you could 
do, depending on the kinds of help you want to provide for your part editor. You’ll 
find samples of the resources mentioned in the article on this issue’s CD. 

If you haven’t worked with Apple Guide before, you might want to read “Giving 
Users Help With Apple Guide” in develop Issue 1ft before tackling the new concepts 
presented here. Apple Guide Cmiplete is the definitive reference, though the current 
(1995) edition doesn’t cover Apple Guide 2.1. 

HOW APPLE GUIDE BUILDS THE HELP MENU 

From the beginning, one of the strengths of Apple Guide has been that it enables 
guide authors to create guides without requiring modification of the application 
being guided. While most other new Toolbox managers were saying, “To support me, 
just add a NewManagerldle call in your main event loop,” Apple Guide said simply, 

“I work just fine without any modifications to your application at all!” One of the key 
elements enabling Apple Guide to work without requiring changes to any code is 
Apple Guide’s automatic population of the Help menu. 

has also been called the Guide menu at certain times in its history 
but both names refer to the same menu (the one labeled with a question mark).* 

The algorithm Apple Guide uses to determine how to populate the Help menu, 
although simple on the surface, has a number of subtleties. With each new release, 
the algorithm has been extended somewhat. To understand how the Help menu 
is populated in Apple Guide 2.1, let’s look at how the population algorithm has 
developed over time. You Apple Guide experts might even discover some little-known 
features. 

Table 1 presents a summary of how the different versions of Apple Guide populate 
the Help menu; details follow. 


Table 1 * How populating the Help menu has evolved 


Apple Guide version 

Candidates 

Exclusions 

Placement in menu 

Original Apple Guide 

Guide files in 
application's 
folder. 

Based on <App Creator>, 
<Gestalt>, 1 GLfy 1 . 

Based on type (About, Tutorial, Help, 
Shortcuts, Other). There can be only one 
guide file of each type except Other, 

Apple Guide 2,0 

Add guide files 
in Global Guide 

Files folder. 

No changes. 

Guide files m application's folder take 
precedence over those in Global Guide 
Files folder. 

Apple Guide 2.1 

For OpenDoc shell 
documents, change 
application's folder 
to mean document's 
folder. 

Add an exclusion check 
based on resources of type 
’prts 1 (for OpenDoc) and 
’apsg 1 (for applications). 

Mufti process guide files fprts 1 For OpenDoc, 
"mill 1 for others), if present, are accessed 
through the “Process Nome Guide" item in 
the Help type menu position. Guide files 
with the ’apsg’ resource appear in the Help 
menus of multiple applications. 


Nate: All candidates are determined when the Help menu is built. Exclusions are applied at the time the menu is built, except for the 
’prts 1 resource test, which is applied when Apple Guide is launched. 
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"ORIGINAL" APPLE GUIDE 

The general process of populating the Help menu hasn't changed since Apple Guide 
was first introduced. At application launch time, Apple Guide does the following: 

1 * creates a list of possible guide file candidates 

2. excludes any candidates that don’t match required criteria 

3. puts the names of all remaining guide files in their requested positions in the 
Help menu 

For the original version of Apple Guide (any version before Apple Guide 2.0), the list 
of candidates is created by searching for all guide files that are in the same folder as 
the application being launched and that aren't Mixin guide files {see Apple Guide 
Complete , page 2-14, for details about Mixin guide files). A guide file with an alias in 
the application’s folder would also be added to the list of candidates. 

Apple Guide then sees if any candidates should be excluded by subjecting them to 
these tests: 

L If the guide file contains an <App Creator> command specifying a value that 
doesn’t match the signature of the current application, iris excluded (see 
Apple Guide Complete, page 10-8). 

2. If the guide file specifies one or more <Gestait> checks and no <Gestalt> 
selector returns its required value, the guide file is excluded (see Apple Guide 
Complete, page 10-10). 

3. If die guide file specifies exactly one <Gestalt> check whose selector is 
"QLfy, Apple Guide looks in the guide file’s resource fork for a resource of 
type 'QLfy with a resource ID equal to the requiredValue parameter of the 
<Gestalv> command. If it finds such a resource, it assumes iris a 680x0 code 
resource that takes no parameters and returns a short in register DO {standard 
C calling conventions). It calls the resource code and, if the result is 0, the 
guide file is excluded (see develop Issue 18, page 19). 

Apple Guide then tries to place the name of each remaining candidate in the position 
it requested with the helpType parameter of the <Help Mcnu> command (see Apple 
Guide Coftrplete, page 10-14), Placement of die names of different types of guide files 
is shown in Figure 1. If two or more final candidate guide files have the same type 
and that type isn’t Other, Apple Guide includes the name of the first guide file of that 
type (by alphabetical order) and excludes the others. The names of all guide files of 
type Other appear in die Help menu. 



_ 

m 

About — 

About My Guides.,, 


Show Balloons 

Tutorial — 
Help — 
Shortcuts — 

— Tutorial 

- Guide 

Shortcuts 


Other — 

other 1 

Other 2 


Figure 1. Placement of Help menu items by type in original Apple Guide 
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APPLE GUIDE 2.0 

Apple Guide 2.0 (an update to System 7.5 but backward-compatible with System 7 
and 7,1) added some logic to the Help menu population algorithm that hasn't been 
widely documented. The crux was adding a new place to look for candidate guide 
files, called the Global Guide Files folder. The Global Guide Files folder resides in 
the Extensions folder and, as its name suggests, is a place where you can put guide 
files to make them available to all applications. 

When Apple Guide 2.0 is creating its list of candidate guide files for an application, it 
looks both in the folder containing the application and in the Global Guide Files 
folder. When looking to exclude candidates, Apple Guide 2,0 works almost exactly 
like the original Apple Guide — it excludes any guide files from its candidate list that 
don't pass die <App Creator>, <Gestalt>, and ‘QLfy" tests. 

The only difference is in how Apple Guide 2.0 selects an item for the Help menu if 
there are multiple candidates. In the original Apple Guide, if two guide files passed all 
the tests and were of the same type (aside from type Other), the one sorting first 
alphabetically would be chosen for inclusion, in Apple Guide 2.0, if there are two or 
more guide files of the same type, the first one alphabetically is still chosen for 
inclusion, but any guide file in the application's folder is chosen over any guide file in 
the Global Guide Files folder. So, for example, if there are Tutorial guide files in die 
application's folder ant) also in the Global Guide Files folder, those in the Global 
Guide Files folder will he ignored, and the one that's first alphabetically in the 
application's folder will be chosen for inclusion. Names of guide files of type Other 
are added from both the application folder and the Globa! Guide Files folder. 

APPLE GUIDE 2.1 

Apple Guide 2,1 adds two new mechanisms to the process of building the Help menu: 

* the ability to define mulriprocess guide files (with an nilti' or a 'prts' resource) 
and to access these files as a group through a single menu item that presents 
the user with a combined Full Access window (available in both OpenDoc 
part editors and conventional applications) 

• die ability to specify a list of application signatures that your guide supports 
(with an 'apsg' resource), so that die name of your guide will appear in the 

I lelp menu for each of those applications 

We’ll look at these new mechanisms in more detail in the next section. 

In addition, Apple Guide 2.1 supports document-specific help. Recall that when 
creating a list of candidate guide files, Apple Guide 2.0 looks in the same folder as the 
application and in the Global Guide Files folder, Apple Guide 2.1 behaves exactly the 
same way for conventional applications, but for OpenDoc documents launched via 
the OpenDoc shell application, Apple Guide 2.1 treats the document's folder as the 
“application’s folder,” so it looks in die same folder as the document for guide files, 
rather than in the same folder as the OpenDoc shell application (besides searching 
the Global Guide Files folder). As a result, the names of guide files in the same folder 
as the OpenDoc shell application never appear in the Help menu; the names of guide 
files in the same folder as an OpenDoc document can appear in the Help menu for 
that document. 

A CLOSER LOOK AT APPLE GUIDE 2.1 

Apple Guide 2,1 introduces a new concept: the multiprocess guide file. A multiprocess 
guide file is specified by including in the guide file an 'nilti' resource for conventional 
applications or a prts' resource for OpenDoc part editors. Because these two are so 
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similar, M discuss them together. FU also tell you more about the new ’aps g resource, 
which when added to a guide hie means that the guide file’s name will appear in the 
Help menus of multiple applications. 

USING MULTIPROCESS GUIDE FILES 

Before multiprocess guide files, the name of every guide file that met Apple Guide’s 
criteria for inclusion in the Help menu appeared as its own menu item. Multiprocess 
guide files are different* All multi process guide files that are candidate guide files and 
that aren’t excluded for any reason (other than that there’s more than one of them) 
get grouped together with the Help guide file (if there is one). This group is accessed 
through a single Help menu item labeled “Process Name Guide/ 5 where Process Name 
is the document name for OpenDoc and the application name for conventional 
applications. This item is placed in the menu position that the name of the Help 
guide file would otherwise occupy. Figure 2 shows a Help menu with a multiprocess 
guide item for a Cyberdog document called Peter’s Notebook. 


Multi process guide 
menu item 



About Apple Guide 


Shorn Balloons 


Peter f s Notebook Guide 


Figure 2. A Help menu with a multiprocess guide item 


When users choose the multi process guide menu item from the Help menu in a 
conventional application, they get a combined Full Access window, known as a 
Merged Access window, with these features: 

* Topic areas for each multi process guide and for the Help guide, listed under 
the guide file’s name in the order specified in the guide’s topic area list (see 
Figure 3)* 
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Organizing Saved Addresses 



connect to News the first time? 
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£ 


add a news server? 
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Figure 3* Merged Access window with topic areas 
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* Index terms for each multi process guide, combined, alphabetized, and with 
duplicates merged. When an index term is selected in the left pane, all topics 
associated with the term are listed on the right for all guides (Figure 4). 

* “Look For” search capability, which can search all multiprocess guide files 
independently and return a list combining all the topics that match in each 
guide file (Figure 5). 



Figure 4. Merged Access window with index terms 



Figure 5. Merged Access window with 'Took For" search 
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If a guide file has an Tnlti’ or a ’prts' resource, Apple Guide 2A ignores die guide file 
type specified by the <HeIp Menu> command. However, for backward compatibility, 
you probably should declare your multiprocess guides as type Other using the <Help 









































































































Memi> command so that Apple Guide versions before 2,1 will list them individually 
in the Help menu. 

As I mentioned before, if there are both muitiprocess guide files and a Help guide 
file, die Help guide gets treated as if it were another multiprocess guide and gets 
merged with them. If there's only a Help guide file and no multiprocess guide files for 
an application, the name of the Help guide file appears in its appointed slot in the 
Help menu, just as in previous versions of Apple Guide, Note that if there are any 
multiprocess guides, the Help guide, if supplied, must be a Full Access window guide 
to be listed in the Merged Access window with the multiprocess guide files. 

Multiprocess guide files aren't mix ins, as explained in “Mixin vs. Multiprocess Guide 
Files.” For one thing, multi process guide files are treated independently by Apple 
Guide and thus won't have resource conflicts with other muitiprocess guide files 
(unlike mixins). Furthermore, all muitiprocess guides must have topic areas and index 
terms (that is, they must be Full Access window guides); if they don't, as you might 
expect, they won't be accessible in the Merged Access window. 

The 'prts* resource introduced in Apple Guide 2.1 is expressly for OpenDoc. If the 
current process is an OpenDoc process (any process that supports OpenDoc part 
embedding), guide files with a pro' resource (like those with an 'mld T resource) are 
grouped together in a Merged Access window when the user chooses the Document 
Name Guide item from the Help menu. 

But before Apple Guide adds multiprocess guide files for an OpenDoc process, it 
performs one more exclusion check —- and unlike all the other exclusion criteria, this 
one is applied each time Apple Guide is launched and not when the Help menu is 
built. Apple Guide compares the list of part editor names in the 'prts' resource with 
the list of part editors currently in the active process and adds the guide file only if it 
finds a match. Thus, even though the Global Guide Files folder will likely contain 
multiprocess guide files for every OpenDoc part editor on the user's machine, the 
user will see help only for editors currently in the active process — sort of a “dynamic” 
Merged Access window. If the pits' resource is empty — that is, if it lists no part 
editor names — the guide will always be added to the Merged Access window if the 
current process is an OpenDoc process. 


MIXIN VS. MULTIPROCESS GUIDE FILES 


You might be asking, "What about mixins? Aren't they 
kinda like multi process guide files? When would I use 
mixins instead?" 

Mixin guide files are used to add, delete, or replace 
content in existing guide files. Multiprocess guide files 
can't do this. Mixins work best for small, incremental 
changes, but they require good resource management 
They also require a main guide file to modify. 

Multiprocess guide files in OpenDoc never know which 
other guide files, if any, will be there when OpenDoc 
is loaded, so you can't use a mixin in place of a 
multi process guide file — there may not be a main guide 
file to modify. Also, you don't know which other mixins 
might be there, so resource conflicts could easily occur. 


But you con use a mixin to modify your own multiprocess 

guide if you do the following: 

* Put the <Mixin> command as the first line in your mixin 
source and be sure to reference your multi process 
guide File's .sym file to ovoid resource conflicts. 

* Add all the same exclusions as in your multi process 
guide file. Add additional exclusions if your mixin 
should activate only in special situations. 

* Add an “mltl 1 or a ’prts 1 resource to your mixin if your 
main guide file has one. 

* Make sure your Mixin and your multiprocess guide 
files both use the <Mixin Match> command so that 
your Mixin guide file mixes only into your multiprocess 
guide file. 
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USING ONE GUIDE FOR SEVERAL APPLICATIONS 

Recall that if you specify a creator code in a guide with the <App Creator> command, 
the guide file will he removed from the candidate list unless the application's creator 
code matches- But what if you have a guide for a suite of applications and you want it 
to appear in the Help menu for each of those applications? 

Until now, the only way to do this was to have all the applications in the same 
folder as the guide file or to have a copy of the guide file (or an alias to it) in each 
application’s folder. With Apple Guide 2.1, you can get the desired result much 
more cleanly and easily by adding to your guide file an 'apsg f resource listing the 
application signatures diat your guide supports. Then, with your guide file in the 
Global Guide Files folder, the Help menu will he appropriately populated for every 
listed application. 

If you specify an apsg' resource and use an <App Creater> command, Apple Guide 
2.1 uses only the resource. If there's no resource, the <App Creator> specification is 
used, if it exists. If you specify neither and you put your guide file in the Global Guide 
Files folder, it will appear in the Help menu for every application (which might not be 
what you want and could greatly annoy your users). 

That brings us to the present in the evolution of Apple Guide, Now we'll look at the 
details of getting your guide hie to work with Open Doc. You’ll see how to make help 
for an Open Doc part editor accessible to users, and how to add coachmarks, context 
checks, and events once your guide is up and running. 

GETTING A PART EDITOR'S GUIDE INTO THE HELP MENU 

Now that you know the history of Apple Guide and die Help menu, you've probably 
got a pretty good idea ol how to get your part editor's guide to appear where you 
want it. l.et's outline the preferred method to accomplish this: 

1. Add a 'pi ts' resource Lo your guide file. Use the 'pits' resource to specify all 
the Open Doc part editors your guide should go with — that is, the editors 
that when active should have your guide appear in the Merged Access 
window. Normally, you'll specify only a single part editor, but if you’re 
writing a guide for a collection of related editors, you may list more. If you 
want your guide to show up no matter which part editors arc in the current 
process, use an empty prts' resource (actually two bytes of zeros). 

2. Make your guide an Other guide file and specify a creator code of 'odtm', the 
signature of the Open Doc shell. This ensures that your guide won't appear 
in conventional applications if it ever ends up on a machine with an older 
version of Apple Guide. 

3. Install your guide file in the Global Guide Files folder so that it's available to 
all Open Doc processes, regardless of how OpenDoc was launched. As 
mentioned earlier, since OpenDoc is document-centered rather than 
application-centered, guide files become candidates if they're in the Global 
Guide Files folder or the same folder as the document the user double-clicks 
to launch OpenDoc, so guide hies in the OpenDoc shell application's folder 
won't normally be considered. 

Unless for some reason you want your guide to appear as a multi process guide in 
conventional applications, you don't need and shouldn’t add an 'mid' resource. 

Guide Maker doesn't support the new resources yet, so they must be created by hand 
where required. For the 'pits' resource needed by OpenDoc, I recommend creating a 
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file named MyGuideOpenDocResource that you can then reference from your Guide 
Script source file with the line 

<Resource> "MyGuideOpenDocResource", ALL 

A file on th is issued CD includes samples of these resources and ResEdit templates. 
For the details, in Rez Format, see “New Apple Guide Resources.’ 1 

You can provide access to your guide in ways other than Apple Guide’s automatic 
population of the Help menu if you don’t mind a little code modification — all of the 
Apple Guide API calls still work just fine in Open Doc, so you can add a Guide button 
or a Help menu item to your part editor and then call AGOpen when the user dicks 
or chooses that item. (See “Cjiving Users Help With Apple Guide” in develop Issue 1H 
For a detailed description of the Apple Guide APL) 

Don't modify the Help menu From within your port editor with the Toolbox coifs 
HMGetHelpMenuHondle and AppendMenu (although it's perfectly acceptable to do 
this from within an application — even an application that supports OpenDoc 
embedding). The system, OpenDoc, and Apple Guide don't support this kind of use 
and many problems will occur* 

If all you need is a simple “book” guide for your part editor, with no coachjuarks, 
context checks, or Apple events, you don’t need to do anything else — carrying out 
the three steps listed above is enough to make Apple Guide help for your part editor 
accessible within OpenDoc, If you want to provide more elaborate help, read on. 

GIVING MORE ELABORATE HELP IN OPENDOC 

Once your guide is up and running and the user has selected a topic, Apple Guide 2A 
looks and acts just like previous versions of Apple Guide, The guide window appears 
on top of the application, and users can click through the guide’s panels as they work 


NEW APPLE GUIDE RESOURCES 

Apple Guide 2,1 introduces the 'mfti 1 , ’prts', and r apsg’ 
resources to support its new features. These resources 
must be created by hand. 

The ’mlti' resource, by its mere existence, means the file is 
a multiprocess guide file. This resource is four bytes of 
zeros. 

type mlti' { 
longint = 0; 

}? 

The ’pis' resource is just like an 'STR# 1 resource — a short 
specifying the number of part editor names, followed by 
the names, 

type ’prts' as 'STR# f r 

The [ opsg r resource is a long specifying the number of 
application signatures, followed by those signatures. 


type 'apsg* { 

longint » $$Countof(SigArray); 
array SigArray { 
literal longint; 

}; 

u 

Here are some examples of using these Rez templates: 

// Multiprocess guide file — conventional app 
resource 'mlti 1 (1000) {}; 

// Multiprocess guide for OpenDoc to be merged 
// when "Test Clock' is in the active process 
resource 'prts' (1000) {{ 

"Test Clock" 

}}; 

// Guide only these two applications 
resource 'apsg' (1000) {{ 

’ttxt', 1 MSWD' 

}}? 


USING APPLE GUIDE 2.1 WITH OPENDOC 


61 






in the application* But when die guide tries to communicate with the outside world, 
some things become more complicated. Specifically, you may have to take additional 
steps when you try to do any of the following: 

• Use a coachmark on a part. 

• Get context information (perform context checks) on a part editor. 

• Send Apple events to a part editor* 

The good news is that sending events to other applications such as Apple Guide or 
the Finder, or getting system context information (such as how many monitors die 
computer has) or anything else not specified above, works just the same, so I won't 
talk about those things* Before reviewing the specific changes required to use 
coachmarks, perform context checks on part editors, and send your part editor Apple 
events, I need to discuss the biggest difference in approach required to use Apple 
Guide with OpenDoc: I call it the “target application” problem. 

Apple Guide was written to be very System 7 friendly, so almost everything Apple 
Guide does relies on Apple events. Most of the Apple Guide API calls (such as 
AGInstallContextHandler) secretly use Apple events to get their work done. 
Unfortunately, when Apple events were designed, OpenDoc wasn't around* Apple 
events rely on targeting specific processes (usually identified by application 
signature). Apple Guide assumes that every application has a unique static signature 
and that only one instance of the application will be running at a time. (If you launch 
a second document for an application, the second document is opened in the same 
process as the first one.) Neither of these assumptions holds for OpenDoc. 

The process signature for an OpenDoc process is the application signature for the 
root application. For documents launched with the OpenDoc shell, that signature is 
odtiii'. For documents opened into other applications that support embedded parts 
{as Claris Works will soon), the signature is that of the host application. So if, for 
example, you target a coachmark at the Vxltnf process and your current OpenDoc 
session is running in ClarisWorks, the coachmark won’t fire. 

And there can be more than one process with the same signature running. If you 
already have an OpenDoc document open and go to the Finder to launch a second 
document, it launches as a separate process. So if both documents are launched using 
the OpenDoc shell, there will be two processes with the odtnV signature running 
concurrently. Then, for example, if you target a context check at the 'odtm' process, 
you have no idea which of the two processes will handle the request* 

Even if you somehow could manage to target the correct OpenDoc process, a single 
OpenDoc process can have a number of part editors running inside it — possibly 
multiple instances of the same part editor* How do you target a specific editor inside 
a particular process? 

Don’t abandon hope — all is not lost! But do keep this issue in mind as I describe the 
steps you need to take to use some of the cooler Apple Guide features. 

PROVIDING COACHMARKS 

There are two things you need to do to use coachmarks in OpenDoc: always use the 
Guide Script constant FRONT (FII give examples in a moment), and then use 
context checks to ensure that your panel is displayed only when the user is in the 
right process (that is, you need to ensure that the process you want to coachmark is 
the front process). For the most part, you'll find that coachmarks, except object 
coaches (because of the target limitation), work just fine in OpenDoc. 
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MENU COACHES 

Menu coaches are used to highlight a particular menu and menu item. You can refer 
to a menu name and item by number or name. 

Menu coaches work fine in OpenDoe. The only recommendation I have (whether or 
not you Ye in OpenDoe) is always ro specify menu titles and items by name anti not 
by number. This is especially important in OpenDoe, because individual OpenDoe 
parr editors can add menus and menu items at will (check out Cyber dog for a great 
example of this). For example, to coach the Drafts item in the Documen t menu, use 
something like this; 

<Define Menu Coach> ^DocumentDrafts ", FRONT, REDUNDERLINE, "Document", 
"Drafts,./, RED, UNDERLINE 

WINDOW COACHES 

Window coaches mark static items in windows. They work in OpenDoe as in 
applications. For example, you could coach the user to close die window called Log 
with the following: 

<Define Window Coaeh> "CloseBox", FRONT, REDCXRCLE, "Log", CLOSEBOX 

But to have a window coach highlight a particular element of a part in a window is 
usually impractical in OpenDoe, because the location of a part in a window isn't 
predetermined. A part could be all by itself in its own window or anywhere inside a 
container window. An exception to this is when a part is viewed only in a situation 
w h ere the offset from the window edges is known. A good example of this is the 
Cyberdog Web browser part, shown in Figure 6. The URL (Uniform Resource 
Locator) field is always in the same place because the Web browser is always in its 
own window, so in diis case you could coach die URL field with the following 
window coach: 

<Define Window Coach> "WebURLField", FRONT, REDARROW(1,4), FRONT, 

Rect(0,Q,125,100) 

ITEM COACHES 

Item coaches are used in Apple Guide to coachmark items specified by dialog ID or 
balloon ID. 





M Cyb*rdog Home Page 


ESH 


Location (URL): ht tp : / /c y ber dog.apple com/ 


Figure 6- The Cyberdog Web browser window 


USING APPLE GUIDE 2.1 WITH OPENDQC 


63 




















Dialog IDs work if your Open Doc part editor brings up a standard dialog with 
standard dialog items. Or you can use dialog IDs to eoachmark items in the OpenDoc 
shell dialogs. For example, to coach the Save Draft button in the Drafts dialog, you 
could use the following item coach: 

<Define Item Coach> "SaveDraftButton' 1 , FRONT, REDCIRCLE r Dialogic 1) 

You'll find that because standard Balloon Help doesn’t work in OpenDoc except 
under special circumstances, balloon IDs are probably too tricky to use. The reason 
for this problem is conflicting assumptions in OpenDoc and Apple Guide about die 
accessibility of resources. Apple Guide expects all the balloon resource information to 
lie available in the current resource chain. Logically, one would store balloon resources 
for a part editor in its resource fork, but, due to the intricacies of OpenDoc, a pan 
editor’s resource fork isn't available when Apple Guide needs it. Since Apple Guide 
can’t gel at the Balloon Help resources, it can’t look up a balloon ID’s rectangle, and 
thus you can’t easily use balloon IDs to eoachmark items in OpenDoc. 

OBJECT COACHES 

Object coaches rely on guide code inside a process to return the coaching rectangle. 
The name of the desired object to be coached is passed to the specified target 
application, which responds with die coaching rectangle. 

Unfortunately, Apple Guide allows only one object coach handler per process. If two 
part editors in one OpenDoc process both try to install object coach handlers, the 
second one will override the first one (that is, any object coaches will be handled by 
the second editor and never by the first). This means you can't use object coaches 
reliably with OpenDoc processes. 

If you deride to use object coaches in your part editor because you know that 
yours will be the only one installing an object coach handler, be sure to use the 
OpenDoc API to do the installation.* 

This obstacle to using object coaches in OpenDoc has been noted as a serious concern 
by ma ny people, including Apple Guide authors and those on the Apple Guide and 
OpenDoc teams. Some possible solutions have been proposed. We can hope that 
updated versions of Apple Guide and OpenDoc w ill support one of them in the near 
future {although nothing has been promised yet). 

APPLESCRIPT COACHES 

AppleScript coaches don’t ret]uire a target application at all, so they don’t suffer directly 
from the target application problem. To determine the target rectangle, though, the 
script itself usually has to communicate with one or more OpenDoc part editors. You 
can make part editors scriptsble, but remember to use Open Doc's scripting API, not 
the regular AppleScript calls. 

PERFORMING CONTEXT CHECKS 

There are three sources of context checks for guides written for OpenDoc: 

* the standard suite of context checks (part of the Standard Includes package 
on most Apple Guide CDs) 

* a new r suite of standard OpenDoc context checks {designed expressly for 
OpenDoc) 

* any custom context checks you write for your OpenDoc part editor only 
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THE STANDARD SUITE OF CONTEXT CHECKS 

The standard suite of context checks includes ways of testing basic elements of the 
traditional Macintosh interface. Here are some examples of these context checks: 

* Is a window with a given name the ffontmost window? 

* Does this xMacintosh have more than one monitor? 

* Is the Open item in the File menu enabled? 

The context check definitions and die resources you must include in your guide to 
use them are on any Apple Guide authoring CD (such as the CD that comes with 
Apple Guide Complete , the Custom Solutions CD, or the Mac OS SDK CD), 

These context checks work pretty well in OpenDoc processes. All of the system 
information context checks work (bit depth, printer info, file sharing info, and so on), 
because they all target the Finder for their information. The application information 
context checks work (again, you’ll have to target these with FRONT), except for 
menu item checks, since OpenDuc controls how the menus are stored and displayed. 
At present, if you’re using the standard context checks in an OpenDoc process, you 
can’t determine whether a menu item is enabled, is checked, or exists at all (though 
you can write a custom context check to do this). 

The process context checks do work, but they aren’t very helpful because they’re based 
on target application signatures. For example, asking if the current active process is 
odtm 1 will tell you if the active process is the regular OpenDoc shell but won’t help 
you determine whether it’s some other OpenDoc process (because the user could 
have some other OpenDoc shell application). Nor will this confirm that the active 
process is the desired process (since there could be several OpenDoc processes 
running). 

THE STANDARD OPENDOC CONTEXT CHECKS 

To proride guide authors with tools to answer questions about OpenDoc processes, a 
suite of OpenDoc context checks has been written. For these context checks to work, 
the user must have an OpenDoc shell piug-in called AppleGuidePlugln correctly 
installed. This plug-in is installed automatically when Apple Guide 2,1 is installed If the 
plug-in isn’t installed, all OpenDoc standard context checks will always return FALSE, 

Before we look at the available OpenDoc standard context checks, you should note 
that for every one of these context checks that takes the name of a part editor as one 
of its parameters, there are two variations: if the second SHORT parameter is 0, the 
editor names must match exactly; if the second SHORT parameter is 1, the actual 
editor name need only contain the text specified in the context check. Both variations 
exist for all context checks that take a part editor name. All of these functions return a 
Boolean result (TRUE or FALSE). 

Is the Apple Guide plug-in available? 

<Define Context Check> "IsPluglnAvailable", ‘odag*, FRONT, SHORT;! 

This context check is a way to make sure that the plug-in has been installed correctly 
and is available to run when the next OpenDoc process runs, thus ensuring that any 
standard OpenDoc context check will return a correct result. The only catch is that 
the plug-in isn’t actually installed until the first OpenDoc process has been launched, 
so this check will return FALSE if no OpenDoc process has yet been run, even if the 
plug-in is available. With this limitation in mind, you can define this context check, 
which ties an Apple Guide context check name to one of the resources you included 
above. Then you might use it this way: 
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<Define Sequence> ''How do I do something?" 

<If> IsPlugInAvailable() 

It instruction panels 
<Else> 

It panel saying that this guide requires Apple Guide 2*1 
<End If> 

<End Sequence> 

You probably won’t need to use this context check and will just assume that the Apple 
Guide plug-in was installed correctly 

Is OpenDoc active and frontmost? 

<DCC> "IsOpenDocActiveAndFrontmost"/ 'odag', FRONT, SHORT:2 

Use this context check to see whether the active process is an OpenDoc process. It 
isn’t application signature based and thus will return TRUE for any OpenDoc process, 
no matter what the host application is* 

Is the part editor named "MyPart 1.0" installed? 

<DCC> "PartEditorlnstalled", 'odag 1 , FRONT, SHQRT:4, SHORT:0, LPSTRING 
<DCC> "PartEditorlnstContains", r odag\ FRONT, SH0RT:4, SHORT:!, LPSTRING 

To determine whether a particular part editor is installed in the OpenDoc Editors 
folder and is available, use this context check* It has nothing to do with whether an 
instance of the part editor is currently in the active process* You might use a call like 
PartEditorlnstalled(’’MyPar11.0”) to make sure that a particular part editor has been 
installed on die machine before you tell users to do something that depends on die 
part editor’s being available. This is one of die functions diat takes a part editor name 
as its argument; you could use the less specific version of the function by calling 
PartEditorInstContams( tr MyPart l, ) J but take care — you might end up matching 
someone else’s part editor if you’re too general! 

Is the port editor named "MyParf 1.0" in the active process? 

<DCC> "PartlnAetiveProcesa", 'odag f , FRONT, 5HQRT:6, SHQRT:0, LPSTRING 

This is a way to check whether an instance of the speci fied part editor is in the active 
(frontmost) process. The corresponding part may or may not be in the active (frontmost) 
window. 

Is a "MyPart 1.0" part in the active window or in a nonactive window? 

<DCC> "PartlnActiveWindow", 'odag\ FRONT, SHORT:?, SHORT:0, LPSTRING 
<DCC> "PartlnNonActiveWindow", 'odag*, FRONT, SHORT:8, SHORTiO, LPSTRING 

These two context checks enable you to see whether there’s an instance of the part 
either in or not in the active (frontmost) window. 

Is a "MyPart 1.0" part in the active document or in a nonactive document? 

<DCC> "PartlnActiveDoc*, 'odag', FRONT, SH0RT:14, SHORT:0, LPSTRING 
<DCC> "PartInNonActiveDoc", 'odag', FRONT, SHORT:15, SHORT:0, LPSTRING 

An OpenDoc process can contain multiple documents. A particular document in a 
process might have more than one window. These two context checks enable you to 
see if an instance of the specified part is in any of the active document’s windows or 
any windows of a nonactive document. It’s unlikely you’ll need these checks — most 
of the time you’ll want to check whether a part is in the active window or the active 
process. 
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1$ a "MyPart 1,0" part the active part (the active frame)? 

<DCC> "PartisActiveFrame* f 'odag 1 f FRONT # SHORT:10 f SHORT:0, LPSTRING 

This is a way to check whether an instance of the specified part is the currently active 
part. This is useful to know because a part editor’s menus are usually available only 
when the part is active. 

Is the active part the root part? 

<DCC> " AetivePartlsRoat*, 'odag', FRONT, SHORT:9 

If you need to determine whether the active part is the root part for the active 
document, use this check. 

Does the active part allow embedding? 

<DCC> M ActivePartA1lowsEmbedding n , ' odag’, FRONT, SHORT:5 

With this check you can determine whether the active part is a container part and 
allows other parts to be embedded inside it. You might use this if, as part of a task, 
you need to get the user to drag a new instance of a part into the active container part. 

Is the active document bundled? 

<DCC> "ActiveDocumentIsBundled", 'odag 1 , FRONT f SHORT:3 

This is a way to check whether the active document is bundled. Bundling a document 
prevents any subparts in the document from being activated; clicking on a subpart in 
a bundled document will select the subpart but won’t activate it. In essence, this 
makes all subparts in the document read-only. 

Is the active document dirty? 

<DCC> “ActiveDocumentlsDirty", 'odag', FRONT, SHORT:11 

This is a way to check whether the active document is dirty (needs to be saved). If this 
context check returns TRUE, the Save menu item is enabled. You might use this to 
tell the user to save changes if necessary. 

CUSTOM CONTEXT CHECKS 

If you still need more specific part information that isn’t available through the standard 
suite of context checks or die Open Doc standard context checks, just as with standard 
applications you 5 11 need to write custom context checks. 

To define and use a custom context check, you must work around two difficulties. The 
first is the target application issue we’re now so familiar with. As before, it’s easy to 
work around: when writing the <Define Context Checlo command for your custom 
context check, you’ll need to use the FRONT constant for the target application. The 
second problem concerns the fact that you could have multiple instances of a part 
editor running at the same time, in either the same or a different Open Doc process. 
This is a problem for both the guide author and the custom context check writer. 

The primary concern is for the guide author: if there are multiple instances of the same 
part editor in one or more currently running Open Doc processes, it’s impossible for 
your guide to identify which part editor you’re providing help for. Let’s look at an 
example. Before step 1 of your task, you use the standard OpenDoc context checks to 
make sure an instance of your part is active. You then tell the user to do step 1. Step 2 
requires step 1 to have been completed, so you want to do a custom context check to 
see if step 1 has been done. However, if there are two instances of your part around, 
which instance the custom context check queries is unknown. Users may have 
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successfully completed step 1, but die context check may come back saying they 
haven't. In this case, they'd be stuck at this point and won't be able to continue. 

The context check writer has similar concerns. The way a part editor would install and 
remove a context check handler would probably be to call AGInstallContextHandler 
in its constructor and AGRemoveContextHandler in its destructor If it's done this way, 
anytime a new instance of the part is created it overrides (and removes) the previous 
context handler, so the last instance of the part to be created is the one that will supply 
context information, no matter which process it's in. In addition, when a part editor calls 
AGRemoveContextl landler, it will remove whichever handler is currently installed; if 
one of two instances of the parr is destroyed, the context handler will be removed, 
leaving no context handler for die remaining instance. 

Unfortunately, there's no simple answer to these concerns at this time. There are 
partial solutions for particular cases, though. For example, if you know r that your part 
editor will definitely have exactly one instance, you might just take your chances. If 
you always want to have the context check respond about the currently active instance 
of the part (if the active frame is the desired part), you can write an 'extm' context 
check that you install in your guide that asks OpenDoc for the currendy active frame, 
and if the part behind that frame is your part, do some context checking on it. As 
more people try to tackle custom context checking, better solutions will evolve, 
perhaps using the ODExtension mechanism of OpenDoc. 

APPLE EVENTS AND APPLESCRIPT 

Sometimes you also want to send Apple events or launch AppleScript scripts from your 
guide when a user clicks a particular button or goes to a particular panel. As Fve said 
before, this is still possible in OpenDoc part editor guides. The only thing that's more 
challenging is when you want to send an event to your part editor, OpenDoc supports 
Apple event handling for part editors by overriding a number of the standard Apple 
event Toolbox routines and by providing a way to target a particular part editor. 
Explaining how to do this is beyond die scope of this article; for more information, read 
the OpenDoc Programmer's Guide , especially Chapter 9, “Semantic Events and Scripting.” 

REACH OUT AND GUIDE SOMEONE 

As you can see, Apple Guide 2.1 provides a number of new features, both for standard 
guides and guides written for OpenDoc part editors. And despite a few limitations, 
writing guides for part editors is as easy as writing them for standalone applications. 
So try it out! Users and reviewers seem to agree: Apple Guide — and thus any 
application or part editor diat has guides — is in a class by itself 
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VINCENT LO 


THE OPENDOC 
ROAD 

Facilitating 
Part Editor 
Unloading 


In the traditional application model, die code for an 
application typically remains loaded until the process 
quits. In OpenDoc, starting with version 1.0.1, a part 
editor is loaded when ids needed during a session and 
unloaded when ids not. As a result, valuable memory 
space can be reclaimed and reused by other part editors, 


point the draft can delete the object to regain the 
memory' it occupies. However, deletion may not he 
immediate when the object’s reference count drops to 
0* In actuality, object deletion is deferred until the 
purge mechanism of the draft is triggered. Typically, a 
purge is initiated by the storage system (for example, 
during a save operation) or by die document shell (such 
as when the document shell realizes that memory is 
running low). 

In response to a purge request, the draft deletes all the 
persistent objects and storage units that aren’t in use — 
that is, objects whose reference count is 0. When all the 
part objects belonging to a certain part editor are 
deleted, SOM calls the Code Fragment Manager 
(CFM) to unload the part editor library. The CFM 
calls the CFMTerminate routine of the part editor 
library, and both the code and data sections of the 
library are destroyed. Some details of how the library 
is unloaded depend on the kind of SOM class it 
contains — either static or dynamic. 


Even though part editor unloading is mostly transparent 
to part editors, there are a few things a part editor 
should do to ensure the success of this scheme. I’ll 
describe these things after giving you a closer look at 
how part editor unloading works. Pay careful attention, 
because the crash you prevent may be your own. 

HOW PART EDITOR UNLOADING WORKS 

The part editor unloading mechanism is enabled by 
facilities provided by SOMobjects™ for Mac OS (the 
Apple implementation for the xMarintosh of the IBM 
SOM ,M technology). The basis of part editor unloading 
is a reference-counting system that enables OpenDoc 
to keep track of which part objects are in use. Ill explain 
reference counting and then give the gory details of 
how part libraries are unloaded, which differs for static 
and dynamic classes. 

Every persistent object (part, frame, link, and so on) in 
OpenDoc is given a reference count by the draft that 
creates it. When the object is first created or acquired, 
its reference count is initialized tu 1. Whenever the 
object is acquired after that (through cither die draft’s 
or the object’s Acquire method), its reference count is 
incremented by 1. Whenever the object is released (by 
a call to the object’s Release method), its reference 
count is decremented by 1. 

When all clients have released their references to an 
object, the reference count of the object is 0, and at this 


Objects created using new className and SOM kernel 
services (soniNewObject, somNewClassReference, and 
SOMo b ject: :So raGetC 1 ass) are static class objects. Most 
(if not all) objects created by a part editor fall into this 
category A static class is unloaded when the code that 
created the static class object is unloaded. Therefore, 
when a part editor is unloaded, all static classes in the 
same library are unloaded as well. Other interdependent 
libraries may also be unloaded; there will be more on 
this later. 

Objects created using the runtime name or ID class- 
lookup services of SOM (for example, SOMClassMgru 
somFindClass, somNewObjectByName, or 
somGetDynamicClassReference) are dynamic class 
objects. OpenDoc parts are dynamic class objects, since 
they’re created by name. Extension objects are also 
dynamic because ODExtension is implemented as a 
dynamic class; subclasses of ODExtension inherit its 
dynamic property as long as they call the parent’s 
InitExtension method. Other OpenDoc classes will be 
converted to dynamic classes as the need arises; check 
die notes accompanying future OpenDoc releases for a 
listing of these, 

A dynamic class guarantees that its code and the code 
for its inherited classes won’t be unloaded until the last 
object of the class is deleted. When the last instance of 
a part class is deleted, SOM unloads the CFM library 
containing the part class. 


VINCENT LO is Apple's technical lead for OpenDoc. in his leisure Kong for many years convinced him that no food can scare him, 
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REFERENCE-COUNTING GOTCHAS 

Every persistent object must have a correct reference 
count for the part editor unloading mechanism to 
work. If a part object has a reference count that's higher 
than the correct count, the object will remain valid 
throughout the session even though it's no longer being 
used. This object will keep its associated part editor 
library from being unloaded until the process quits. 
Conversely, if an object has a reference count that errs 
on the low side, the object may be deleted, causing its 
library to be unloaded. Referencing an invalid object 
pointer usually results in a crash. 

The best way to avoid reference-count errors is to 
familiarize yourself with OpenDoc persistent objects 
and follow the recipes oudined in the OpenDoc 
Programmer's Guide for the Mac OS . Be sure to pay 
special attention to the following potential trouble 
spots. 

Avoid self-referencing. If a part object keeps a 
reference to itself, its reference count will be at least 1 
and its part editor library won't be unloaded until the 
session ends. Since a reference to the part is passed in 
as an argument in every ODPart method, a part 
shouldn't need to store a reference to itself. 

Break circular references between parts and 
frames. Each display frame has a reference to its part 
(after the part has been internalized). Even though a 
part isn't required to keep a reference to its display 
frames, most parts do so for convenience. This creates 
a circular reference be ween a part and its display 
frames, so the reference count alone won't indicate when 
deleting a part is appropriate. The situation becomes 
more complicated when the part has embedded frames 
and also keeps references to them. 

To break these circular references, OpenDoc offers the 
Close and Remove protocols, 

* The Close protocol is triggered when a containing 
part decides to get rid of its runtime-embedded 
frame objects. The containing part calls the 
embedded frame’s Close method. The frame first 
calls its part's DisplayFrameCIosed method, which 
should release its reference to the display frame and 
close its embedded frames (if any) before releasing 
its reference to the part. 

* The Remove protocol works similarly to the Close 
protocol. However, the protocol is triggered when a 
containing part decides to remove its embedded 
frames from both runtime storage and persistent 
storage. The Remove protocol is propagated 

th rough the O D Pa rt:: D i splayFra me Remove d and 
ODFramer:Remove methods. 


Un register frames and parts when idle time is no 
[anger needed. When a part registers its frame with 
the OpenDoc dispatcher for idle time, the dispatcher 
retains a reference to the frame. Until the part editor 
unregisters the frame object from the dispatcher, the 
object will remain resident in memory with a reference 
count greater than 0. This will prevent the object from 
being deleted and its library from being unloaded. The 
part editor should unregister the frame when the 
Remove or Close protocol is triggered. 

On rare occasions, a part may have a display frame 
that's not in the frame hierarchy originated from the 
root frame. For example, a part may have some frames 
stored for the View in Window command. Don't 
internalize those frames and register them for idle time 
until the frames are actually used, 

A part may also register itself with the OpenDoc 
dispatcher for idle time. As in the case of registered 
frames, the dispatcher retains a reference to the part 
object. To ensure that the object is deleted and that its 
library is unloaded at the earliest possible time, the part 
editor must un register itself from the dispatcher as 
soon as idle time is no longer needed. This usually 
occurs when all the part's display frames have been 
closed or removed. 

Watch extensions far reference-counting problems. 

Open Doc's extension mechanism enables separate parts 
in a document to communicate with each other directly. 
By creating an associated extension object, a part editor 
can extend its part interface to satisfy special needs. To 
enable efficient communication, the extension object 
maintains a reference to the part object that created it; 
the part typically keeps a reference to the extension so 
that it can give out the same extension object again if 
it T s requested. 

In general, an extension object is released before its 
creator, thus preventing any reference-counting 
problem for the part. But if the reference count of the 
extension object isn't maintained correctly, or if the 
client of the extension object refuses to release it, the 
part object can detach the extension object from itself 
by calling ODExtension::BaseRemoved. A well-behaved 
extension object should then report errors to clients 
when it’s being accessed. An even better idea is to avoid 
using the base removal mechanism and instead to 
define the scope and lifespan of an extension. 

A LIBRARY-UNLOADING GOTCHA 

When a part editor is unloaded, SOM unloads the 
CFM library associated with the part editor. Moreover, 
if there's another library in the same library closure as 
the part editor, the CFM will unload it if it doesn't 
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Listing 1 . Creating a dynamic object with ODNewObject 
#include "ODNewObj.h" 

GDObjectNameSpace* objNameSpace = (ODObjectNameSpace*) nameSpHgr->CreateNameSpace(ev l 

kOSAScriptingTool, kODNULL, 1, kODNS DataTypeODObj ect); 
Sample_ScriptRunnerAgent* agent = (Sample^ScriptRunnerAgent*) 

ODNewObject("Samples iScriptRunnerAgent"); 

objNameSpace->Register(ev, kGSAScriptingTool, agent); 


belong to another library closure. (A library closure is a 
group of shared libraries whose interdependencies 
cause them to be loaded together by the CFM.} This 
means that code other than the part editor residing in 
the same CFM library closure is unloaded as well. If 
the developer hasn’t foreseen this possibility, it can lead 
to unfortunate consequences. 

Let’s consider a typical example. A part editor creates a 
SOM object from a static class that resides in the same 
library closure as the part editor. The part editor then 
installs the object in a name space so that others can 
access it. If this object doesn’t hold a reference to the 
part, the part may be deleted (and its library closure 
unloaded) when the object reference is still in the name 
space. The next time this object is used, a crash will 
likely occur because the code associated with the object 
has been unloaded with the part editor. 

To prevent this from happening, you should ensure that 
no class whose code resides in the same library closure 
as the part editor outlives the part itself. If an object 
must outlive the part that creates it, the object should 


be created dynamically, OpenDoc provides a utility 
function, ODNewObject, to create objects by name. 
The code in Listing 1 illustrates how a dynamic object 
is created with ODNewObject. 

As mentioned earlier, parts and extensions are dynamic 
objects and thus don’t require ODNewObject. 
ODNewObject is used mainly on SOM classes that a 
part developer has created. 

Once a class has been accessed dynamically, the class 
remains dynamic until the process exits or the use 
count of the class maintained by SOM goes to 0. Until 
then, all object references created for the class are 
considered dynamic by SOM. 

COUNTING ON YOU 

Part editor unloading in OpenDoc is a great scheme 
for managing memory efficiently. But its success 
depends on the cooperation of each and every part 
editor. If you keep in mind the gotchas detailed in this 
column, your part editor will avoid the pitfalls and reap 
tile benefits of wise resource use. 


Thanks to Dave Bice, Erik Eidt, and Troy Gaul For reviewing this 
column, * 
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Mac OS 8 Assistants in System 7 Applications 



JOSE ARC ELLA N A AND 


ARNO GOURDOL 


Assistants are a key part of the Mac OS 8 help system,. An assistant 
makes an application's features easier to use and more readily accessible. 
In anticipation of Mac OS 8, this article will show you how to build 
Mac OS 8-style assistants into your System 7 applications, from design 
to implementation. We illustrate this with a sample assistant developed 
for the Internet Configuration System. 


1 Developers are constantly pursuing two goals that seem to be at cross-purposes; 
making applications more powerful and making them easier to use. All too often, 
power brings complexity, when in fact power can be used to simplify things for the 
user* Assistants can make the powerful features you're building into your applications 
easier to access and handle* 
y\ 

N An assistant offers the user an alternate interface. It focuses on a specific activity that 
the average user is likely to want to do and frames the application's functionality to 
support that activity. The defining aspect of an assistant is the interview, in which the 
user is asked to supply information about preferences and typical activities 
accomplished with the application. 

Although assistants can be implemented under System 7, they'll be able to do more 
using Mac OS 8 technologies. In this article, we talk about what Mac OS 8 assistants 
are and give some general guidelines for designing an interview. We also provide an 
example of how to implement an interview in System 7, Our sample assistant helps 
users with die Internet Configuration System (Internet Con fig), a utility for setting 
preferences for Internet applications, Internet Con fig is described in detail in the 
article “Implementing Shared Internet Preferences With Internet Config” in develop 
Issue 23. The source code for the Internet Setup Assistant is included on this issue's CD. 


The final name far assistants, which have also been called experts, has not 
been decided at the time of this writing. Whichever the final name, the interview- 
based interaction that forms the basis of assistants will be an integral part of the 
Mac OS 8 help system.* 
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INTRODUCING ASSISTANTS 

An assistant is a small single-purpose application that can do any or all of the 
following: 

* frame computer-based tasks in terms of real-world activity 

* hide details from the user by filtering out options that aren't applicable 

* pull together elements from different parts of die user interface to support a 
single activity 

* manage tasks so that they're executed on demand or when a specific 
condition becomes true 

* help the user provide the information needed by conducting interviews 

* make reasonable assumptions, based on user context and user activity, that 
work for the vast majority of users 

For example, a resunie-formatting assistant would ask the user how formal or casual 
the resume should be. It would then make assumptions, hiding such details as 
typeface selection and paragraph formatting. An assistant for maintaining a computer 
would use task scheduling to check for viruses when it makes sense, optimize the hard 
disk when it needs to, and so on. 

At first glance, assistants might seem to resemble Microsoft’s wizards. Currently, 
however, there are differences between them. Wizards don't make reasonable 
assumptions based on user context and user activity. Instead of filtering out options 
that aren’t applicable, they present all options. While assistants provide an alternate 
interface to an application or set of applications, wizards might be the only user 
interface to a task, and they aren't capable of pulling together elements from other 
places in the interface. Wizards also can’t schedule tasks for later execution. 

WHEN TO USE ASSISTANTS 

Assistants are meant to augment and not replace the more direct ways to control your 
application. They shouldn’t be used to cover up a flawed user interface design, such as 
dialog boxes or commands that are too difficult to figure out. Users should always be 
able to do directly in the program’s primary interlace whatever an assistant does for 
them indirectly, though it might take more steps to accomplish the task in the 
primary interface. 

How do you determine when a specific area of the user interface needs a redesign and 
when it could use an assistant? In general, an assistant is most effective when it 
supports an activity that many users want to perform with your application but that 
can only be accomplished if the user has a bettcr-than-average familiarity with your 
application's feature set and user interface. For example, we developed an assistant for 
Internet Config because it takes several steps in different places of the interface to set 
up your Internet preferences for the first time. 

THE INTERVIEW 

An assistant conducts a brief interview, consisting of a series of simple questions, to 
get die information it needs from the user. The Interview should be: 

* Short. Ask as few questions as possible. To minimize the number of questions, 
the assistant should make as many reasonable assumptions as possible. 

* Simple. Make die questions easy to answer. If a difficult question needs to be 
asked, the interview should provide information that helps the user answer 
the question. 
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* Concise. No words should be wasted, even when providing information to 
help the user answer a question. 

* Neutral. The tone should be conversational and friendly* not too familiar or 
too cold. 

Note that an interview isn’t a dialog box, nor is it a dialog box taken apart and presented 
in a series of smaller dialog boxes. Adding “Assistant” to the name of a command that 
calls up a dialog box doesn’t make the dialog box an interview or the command an 
assistant. Finally* the interview isn’t a way to give the computer a personality. 

THE INTERVIEW WINDOW 

The assistant interview takes place in a fixed-size, movable window. Whether it 5 $ a 
regular (document) window, a modal window, or a floating window depends on the 
context from which you anticipate it being invoked. Assistants should be accessible from 
appropriate places in your user interface, such as through a menu item or a button in 
a dialog box. They should be accessible by name (so that the name of the menu item or 
button is the name of the assistant) or, if the context is clear, by the words “Assist Me,” 

The interview window contains header, content* and navigation areas, as you can see 
in Figure L 

* If the interview window is a document window, the assistant’s name appears 
in the tide bar and the header area displays the interview phase that the user 
is in. If it’s not a document window, the header area displays the assistant’s 
name followed by a colon and the interview' phase. 

* The content area contains text (usually a question and a brief explanation) 
and editable text fields and other controls that are used to answer questions 
and enter information. 

* The navigation area contains buttons that help the user move through the 
interview, such as left and right arrow buttons, which lead to the previous or 
next panel, and a Go Back button that takes the user back to the context from 
which the assistant was opened. A number between the left and right arrow 
buttons indicates how many panels the user has been through (see Figure 1). 

DESIGNING AN ASSISTANT FOR INTERNET CONFIG 

To demonstrate how r to add an assistant to your application, the rest of this article 
describes how' we designed and implemented an assistant for Internet Config, a 
popular shareware utility program. 

With Internet Config, the user can create a single file that stores preferences and 
settings for all Internet services. As long as an e-mail program, Web browser, or other 
Internet application uses the Internet Config preferences file* the user doesn’t have to 
reenter Internet preferences for each program. 

Internet Con fig’s central location for user interaction is die window shown in Figure 
2. Clicking each button in the main window brings up a window in which the user 
enters information and secs preferences. 

Internet Config enables users to store a broad range of preferences, from e-mail 
addresses to file conversion formats. Most users never need to set many of these 
preferences* but the dedicated Internet habitue probably finds them all useful. Internet 
Config risks being overwhelming for the sake of completeness — a perfect opportunity 
for an assistant. Our assistant makes Internet Config easier to use by helping the user 
create a preferences file that stores only the preferences that are most commonly set. 
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Figure 1 , A typical assistant interview window 



Figure 2. Internet Config's main window 

DECIDING WHAT THE ASSISTANT WILL DO 

In designing an assistant, you need to determine what most of your users will want to 
do. In die case of Internet Config, recent market studies show that most people use 
the Internet for e-mail, browsing, and downloading files. Given that information, the 
Internet Config assistant’s functionality should be limited to setting preferences in 
those areas. The power-surfer minority that wants, for example, to change the default 
text editor can still do so direcdv through Internet Config’s interface. 

Assistants should he made available from wherever they make sense. For the Internet 
Setup Assistant, it would be helpful to add an Assist Me button to the main Internet 
Config window and an Internet Setup Assistant command to the Help menu. 
Application programs that use Internet Config could have a similar button in logical 
places in their user interfaces. In addition, the Internet Setup Assistant could be 
automatically displayed the first time the user launches Internet Config, 

THE INTERNET CONFIG INTERVIEW 

Our interview will elicit the information we need in order to store a simplified set 
of preferences for the user. As shown in Figure 3, the interview begins with an 
introduction that tells the user in plain language the type of questions that will be 
asked and describes what the assistant will do (or not do) based on the user’s answers. 
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Figure 3. The Internet Setup Assistant introduction 

The next panel, titled “Personal Information,” was shown earlier in Figure L This 
panel poses two questions that are easy to answer: it asks for the user's name (filling in 
a default supplied by the file sharing setup) and company or organization. This starts 
the interview off smoothly while still obtaining necessary information. 

The remaining interview panels that ask questions are listed below (in the order they 
appear) and are shown in Figure 4. Note that for a few of die questions, the assistant 
provides some information because the questions might lie too difficult for some 
users to answer. The goal is to keep the interview self-contained, so that the user 
doesn't need to go to Apple Guide or a manual to figure out what to do. 

* Geographic Location —- This panel asks a question that doesn't directly 
relate to what the assistant does for die user. Many users might be confused 
if asked to select an FTP server; instead, the interview asks for the user's 
location and then die assistant uses die answer to make a reasonable guess as 
to what the user's default FTP servers are. 

* E-mail Address and Password — The password appears as bullets when 
typed and is encrypted. 

* E-mail Account and Host Computer 

* Signature — This panel asks for a “signature” to be appended to the user's 
e-mail messages. A line of hyphens is supplied as the default. 

* World Wide Web Home Page — In Internet Config, setting the Web home 
page preference takes place in the Other Services w indow, listed among less 
commonly used preferences such as die WAIS gateway and the Whois host. 
Many users might be stumped by these options and not find what they're 
looking for. Since we've determined that most users are interested in setting 
their Web site, the interview covers setting this preference. The default Web 
site entered is taken from the Web browser program. 

* Newsgroup Host Computer 
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■J: - Internet Setup Assistant ^ € .. 

Geographic Location 

Vhere art you located? 

Click on your approximate location. 



SUE 

Geographic Location 



E-mail Account and Host Computer 



World Wide Web Home Pope 

Figure 4. internet Setup Assistant interview questions 


E-mail Address and Password 

The next few questions ore about e-mail setting? If you do not know the 
answers to any of these questions, ask your system administrator or 
e-mail account provider. 

Vhat is your e-mail address? 

This address serves os the return address for messages that you send, 
and it is where people will send you e-mail 

Vhat is your e-mail passvord? 


If you leave your password blank, you will have to enter your 
password when you want to receive mail 


SI*E 


E-mail Address and Password 



Signature 



Newsgroup Host Computer 
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When a user types an answer that's dearly wrong (such as an e-mail address that doesn't 
include the © character), we recommend that you integrate the error trapping into 
the flow of the interview questions, rather than presenting an alert box. For example, 
when the user dicks the right arrow button and there are invalid values in the current 
panel, the next panel should point out the error and restate the question. The goal is 
to preserve the question-and-answer, conversational characteristics of the interview. 

Finally, when the assistant has asked all the questions, it presents the conclusion panel 
(Figure 5). The user can see more details by clicking the Show Details button (which 
then changes to Hide Details); the assistant shows the information it will use in 
creating the Internet preferences file (name, organization, e-mail address, and so on), 
summarizing die user’s interview responses. 


Internet Setup Assistant 


Conclusion 


Based on your answers f this assistant is ready to set up your basic 
Internet browsing t e-mail, and newsgroup connections. 


[show Details] 


[ Cancel ][ Go Ahead ] 


Lll 9 [E3 


Figure 5. The Internet Setup Assistant conclusion 


That’s it: ten questions in seven panels, plus an introduction and a conclusion. 


IMPLEMENTING THE INTERVIEW 

You can use your favorite application framework to develop an assistant, or w rite it 
from scratch as a small application. On this issue’s CD, we provide sample code for 
developing an assistant. We don’t recommend using Apple Guide to conduct the 
interviews. Assistants and Apple Guide are different components of the help system; 
they should look related but still different from each other. Also, Apple Guide is a 
less-than-efficient tool for implementing assistant interviews. 

The programming techniques used in this example are specific to System 7 hut will 
continue to work under Mac OS 8. As long as you avoid using undocumented features 
or directly accessing data structures that have an accessor routine, your code should 
work fine under Mac OS 8. In addition, if you insulate your code from specifics of the 
Macintosh Toolbox, it wi 11 be easier to add Mac OS 8 features later on. For some 
details about Mac OS 8 compatibility, see the article “Pl annin g for Mac OS 8 
Compatibility” in develop Issue 26. 
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Our assistant is based on a simple framework that provides a lightweight object- 
oriented coating on top of die Macinosh Toolbox, For example, we have classes that 
provide an object-oriented layer on top of Point (CPoint), Rect (CRect), WindowPtr 
(CWindow), DialogPtr (CDialog), and so on. We also have a simple application shell, 
TAppIication, Those files are grouped in the framework folder. 

The classes aren't dependent on each other, so you can use them easily in your 
existing application. You can create an assistant dialog by using an object of a 
TAssistant subclass and sending it the appropriate events. Your usual framework 
can still be used for handling your event loop and your application's windows. To 
implement the appearance of assistants using your own framework, check out the 
TAssistant class to see how weVe done it. 

The interview is presented in a dialog by a TAssistant object. The class TAssistant is a 
subclass of CMultiDialog, which allows you to have subdialogs that can be switched 
in and out as needed. You could use a similar technique to switch among multiple 
panels in a preferences dialog. Our implementation uses the ShortenDITL and 
AppendDITL routines, as shown in Listing 1, For another way to change panels, see 
the article ^Multipane Dialogs” in develop Issue 23. 


Listing 1* Changing panels in the assistant's interview 

void CMultiDialog::5etSubDialog(SIntl6 subDialogID) 

{ 

if (GetWindowRef() == NULL) 

CreateWindow(); 

if (GetSubDialog() 1- subDialogID) { 

// Save parameters in current panel, 
for (int i = 0? i < kDialogParametersCount; i++) { 
if {fParameters[i].dialogItern 1= 0) 

GetltemText(fParameters[i].dialogltem, fParameters[iJ * value); 

> 

// Remove items from current dialog, 
if (fSubDialogID > 0) 

ShortenDITL[GetDialogRef(), 

CountDITL(GetDialogRef{)) - fCommonIterns); 

fSubDialogID = subDialogID; 

< 

// Add new dialog items to the dialog. 

Handle items = GetResource( r DITL 1 , GetSubDialog()); 
assert(items l = NULL); 

AppendDITL(GetDialogRef(}, items, overlayDITL); 

ReleaseResource(items); 

> 

// Prepare the items in the dialog. 

DoPrepareDialog(); 

} 

) 
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When dialogs are displayed in assistants, you often need to capture the information 
the user enters so that you can put it back if the user goes back to that panel. You 
need to be able to do this untU the user clicks the Go Ahead button in the last panel. 
To simplify this task, we substitute a key string, which is stored in the DITL of the 
dialog, for a string that can change dynamically. The substitution is done each time 
the dialog is displayed. Listing 2 shows how to substitute parameters in the dialog by 
replacing any instance of a key that appears in a static or editable text dialog item 
with a corresponding value. In addition, if an editable text item contains only a key, 
the value entered in the dialog will be associated with the key. This is an extended 
version of the A 0 parameter substitution done by the Dialog Manager. 


Listing 2. Substituting parameter values in dialogs 

void CDialog::SubstituteParameters(void) 

{ 

LazyHandle substitutionText, itemText; 

// Reset the association between parameters and dialog items* 
for (int i = 0; i < kDialogParametersCount? i++) 
fParameters[iJ.dialogltem = 0; 

// Loop through all dialog items. 

for (int item = 1, itemCount = CountDITL(GetDialogRef()]; item <= itemCount; item++) ( 

Sint 16 itemType = GetltemType(item) ; 

If If it’s a static or editable text item... 

if (itemType = kEditTextDialogltem || itemType == kStaticTextDialogltem) { 

Boolean itemTextChanged = false; 

// Copy the text to a handle, 

Str255 itemTextString; 

Get!temText(item, itemTextString); 

itemText,Set{&itemTextString[1], itemTextString[0]); 

// Loop through the parameters, 

for (int j - 0; j < kDialogParametersCount; j++) { 

// If the parameter is used as a nonempty key.,. 
if (fParameters[j].key[0] 1-0) { 

if (itemType “ kEditTextDialogltem && 

::Identicalstring(itemTextString, fParameters[j],key, NULL} == 0) { 

//If the edit field contains only the key, associate the item index with the 
// parameter. The parameter value is updated when the text changes, 
fParameters[j].dialogItem - item; 

} 

{ 

If Replace the key with the parameter value, using the Script Manager, 
substitutionText.Set(& fParameters f j].value(1], fParameters[j].value[0]); 
if (::RepiaceText(itemText, substitutionText, fParameters[j].key) > 0) 
itemTextChanged = true; 

> 

} 

} 

(continued on next pagej 
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Listing 2. Substituting parameter values in dialogs (continued) 
if (iteiriTextChanged) { 

// The item text has changed. Put the modified text back in the dialog item* 
Str255 s; 

s[0] = itemText*GetSize(); 

BlockMoveData(*itemText f [1] f s[0]>; 

SetltemText(item, s); 

> 

> 

} 

} 


When the assistant starts up, we try to capture as much information as possible about 
the user's environment. For example, we use Internet Config information that the 
user has previously entered. 

When the user has entered all the information we ask for and clicked the Go Ahead 
button, we again use Internet Config, this time to set the user’s preferences* The 
CInternetConfig class provides a C++ wrapper to the Internet Config API. See the 
details in the source code. 

THE POWER OF ASSISTANCE 

As you can see, the Internet Setup Assistant doesn’t try to do everything for all users* 
Instead, it helps complete tasks in a way that a majority of users will find useful and 
valuable. 

This sample assistant, though a relatively unambitious demonstration, should start 
you thinking about how to design and develop assistants for your own applications. 
Nothing is quite as powerful as simplicity. 


RELATED READING 

* "Implementing Shared Internet Preferences With Internet Config" by Quinn "The 
Eskimo!", develop Issue 23* 

* "Multipane Dialogs" by Norman Franke, develop Issue 23* 

* "Planning for Mac OS 8 Compatibility" by Steve Falkenburg, develop Issue 26. 

* Aiac OS 8 Revealed by Tony Francis (AddisonAVesley, 1996), Chapter 13, 
"Assistance Services." 
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DAVE EVANS 


BALANCE OF 
POWER 


Stalking the 
Wild Defect 


Once again I found myself bleary eyed and fighting 
sleep, yet I continued to search for understanding. 
Having already struck down two possible causes for my 
enigma, 1 was now searching for new clues, I stubbornly 
refused to rest until I had flushed our the software defect. 

My journey had begun modestly enough as I chanced 
upon a capricious crash in my software, I wondered 
which assumption or logic was at fault. Armed with 
only my low-level debugger, I began a bunt that would 
consume me into the dead of night. On this adventure 
through the dark Mac OS interior, I crossed rivers of 
mode switches, hopped islands of cross-TOC glue, and 
set snares in a jungle of native PowerPC code. 

In this column Til walk you through one facet of that 
relentless pursuit, pointing out die key landmarks I 
used to navigate and demonstrating the tools I used to 
survive. This should help guide you through your own 
future explorations of the innards of PowerPC code, 

ON THE HUNT 

Programming for a Power Macintosh may appear 
similar to your efforts on a 680x0-based Macintosh, hut 
on close inspection you’ll find PowerPC code far more 
interesting to debug. The relatively simple landscape of 
a 680x0 world gives way to confusing and insidious 
terrain on a Power Macintosh. Routine descriptors, 
dual assembly languages, and native glue are obstacles 
that impede your progress. 

My subject was a crash that occurred when PowerPC 
applications called MaxApplZone. 1 was certain the 
problem was in my recent system software changes, but 
1 needed to see what happened right before the crash to 


understand it, I started by setting a breakpoint when an 
application called tMaxAppLZone, {Later Pll describe a 
good technique for setting these breakpoints,) Then 
I traced through the system routine and looked for 
anything startling. 

One application executed the following code just before 
calling MaxApplZone: 


0D93B260 

mi Ir 

0093B2G4 

stw 

0093B268 

stw 

QQ93B26C 

stw 

Q093B27Q 

stw 

0093B274 

stwu 

Q093B278 

lwz 

0093B27C 

bl 


rO 

r3I,-QxDQQ4{SF) 
r30,-GxOGOB(SF) 
r29,-QxG0Qe(SF) 
rO 1 0x0008(SP) 

SF, *“0x0050 (SP) 
r 3 0,-Q x3 9 4 0{RTGC) 
MaxApplZone 


The preamble to MaxApplZone saves registers R29 to 
R3 1 on the stack, creates a stack frame, and loads a local 
variable into R30 from die application's TOC globals 
before calling the routine. If we trace through this and 
then step into the bl (branch and link) instruction to 
MaxApplZone, we find the following: 


0094CBFC 

lwz 

Q094CCOO 

stw 

009 4 CC 0 4 

lwz 

0094CCQ8 

lwz 

0094CCOC 

mtetr 

0094CC10 

betr 


rl2,-0x7E60(RTOC) 
RTOC,0x0014(SP) 
rQ,0x0000(rl2) 
RTOC,0x0004(r12) 
rO 


This code is standard cross-TOC glue. The caller of a 
routine has the responsibility to set die T OC register 
(RTOC) correctly for it. Routines imported from other 
code fragments will have a different TOC value than the 
application. The PowerPC Code Fragment Manager 
supplies die correct TOC value and the address of the 
imported routine in a pair of long words called a 
transition vector f or TVector. In this case, die TVector is 
stored as global data at the application s TOC value 
minus $7E60 bytes. This glue code loads the TVector’s 
address in R12 and then uses that to load the address of 
the routine in R0 and die new TOC value. It uses the 
counter register and the betr (branch to counter register) 
instruction to jump to the correct address, so the return 
address in die link register will not he changed. 

After tracing through this glue code, we find ourselves 
in a different kind of glue. The MaxApplZone TVector 
points to a routine in the Interface!-ib code fragment, 


DAVE EVANS and fellow Apple engineer Rus Max ham look 
another adventure by motorcycle this summer. This lime they 
journeyed to Utah and skirted the Great Sail Lake. Turning north, 
they discovered the beautiful and unspoiled vistas of Idaho. 


Cottonwood flower petals rained on them as they crossed into 
Washington. Hectares of wheat farms and the blustery Columbia 
River guided them to Oregon, One cracked tailpipe and two 
quarts of oil later, they finally arrived home En California,* 
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as listed below. On this computer, you can guess that 
the code fragment is in ROM because the address of 
the routine is very high, $4QA0E30C in this case. Since 
the routine is in ROM, you can’t effectively set a 
breakpoint at its beginning. 

MaxApplZone 


+00000 

40AOE30C 

mflr 

r0 

+00004 

40AQE31Q 

stwu 

SP,-0x0040(SP) 

+00008 

40A0E314 

stw 

rO,Ox0048(SP) 

+OOOOC 

40A0E318 

lis 

rO,0x0001 

+00010 

40A0E31C 

subic 

r5,r0,0x5F9D 

+00014 

40AOE320 

lwz 

r3,MaxApplZone(r0) 

+00018 

40A0E324 

li 

r4,0x3802 

+0001C 

40A0E328 

bl 

CallOSTrapUniversalProc 

+00020 

40A0E32C 

lwz 

RTOC,0x0014(SP) 

+00024 

40AOE330 

lwz 

rl2,0x0046(SP) 

+00028 

40AOE334 

addic 

SP,SP,0x0040 

+0002C 

40A0E338 

mtlr 

rl2 

+00030 

40A0E33C 

blr 



You might expect the real MaxApplZone routine to do 
much more than w r hat appears in this routine. In fact, 
this routine is simply glue for die 680x0 A-trap table: it 
gets the address of MaxApplZone from that trap table 
(don't try this yourself without GetOSTrapAddress, 
kids) and then uses the CallOSTrapUniversalProc 
routine to call the address. 

Most of the routines in InterfaceLib are actually just like 
this glue routine for the trap table. Because the routines 
go through the trap table, PowerPC applications will 
be affected by patches to the trap table; if they were to 
bind directly with the system code fragments, patches 
would he bypassed. 

To continue with our tracing, we must step up to and 
then into CallOSTrapUniversalProc, This takes us to 
more cross-TOC glue: 


40A06D10 

lwz 

r!2,0x0008(RTOC) 

4QA06D14 

stw 

RTOC,0x0014(SP) 

40A06D18 

lwz 

rQ,0x0000(rl2) 

4QA06D1C 

lwz 

RTOC,0x0004(rl2) 

40A06D2G 

mtetr 

rO 

40A06D24 

bctr 



Since Call OSTrapUniversalProc is part of the Mixed 
Mode Manager, it’s implemented in the MixedMode 
code fragment. This cross-TOC glue finds the TVector 
for that routine and calls through to it. When we step 
through this and over the last bctr instruction, we’re 
magically transferred not to the Mixed Mode Manager 
but instead to 680x0 code. Wow! MacsBug knew we 
were calling a universal procedure pointer, so it spared 
ns the trace through the mode switch and took us 


directly to the location of the universal procedure 
pointer, in this case the following 680x0 code: 


0031B160 

MOVE.! 

ApplLimit,DO 

Q031B1G4 

MOVE *L 

HeapEnd,D1 

0031B1G8 

SUB.L 

D1, DO 

0031B16A 

MOVEQ 

#$14,D1 

GQ31B16C 

CMP .L 

DO ,D1 

0Q31B16E 

BLE.S 

*+$OOOA 

0031B170 

MOVEQ 

#$00,DO 

GG31B172 

MOVE.W 

DO,MemErr 

0031B176 

RTS 


0031B178 

JMP 

$00167FCC 


From my experience tracing through the system, Fd 
guess that this 680x0 code is a patch on top of the real 
MaxApplZone, because it compares two numbers and 
in one of only tw o cases jumps to an absolute address. 
The absolute address was probably set wTen this code 
was installed as a patch, and it points to either the real 
MaxApplZone routine or another patch. 

The patch appears to check w r hether the value of the 
ApplLimit low-memory global is within 20 bytes of the 
value of HeapEnd. If so, it simply returns noErr in the 
low-memory global MemErr without calling through 
to the real MaxApplZone. This patch is probably part 
of the system software* designed to fix a bug in the 
ROM without having to replace the entire real 
MaxApplZone routine. 

Now if we trace through this patch and visit the absolute 
address $167FCC from the parch, we find the following: 

No procedure name 


00167FCC 

*_MixedModeMagic 

00167FCE 

BTST 

D3, DO 

Q0167FD0 

ORI.B 

#$00,DO 

O0167FD4 

ORI.B 

#$00,DO 

00167FD3 

ORI.B 

#$3002,DO 

00167FDC 

ORI.B 

#$04,D1 

00167FEO 

ORI.B 

#$8274,D7 

0 016 7 FE 4 

ORI.B 

#$00,DO 

00167FE8 

ORI.B 

#$00,DO 

00167FEC 

ORI.B 

#$AQ36,DO 


Aha! This ugly disassembly is actually a routine 
descriptor in disguise. The_MixedModeMagic trap 
invokes the Mixed Mode Manager from 680x1) code, 
and it always appears at the beginning of a routine 
descriptor. Since this trap is at the beginning of each 
routine descriptor, you can simply construct a routine 
descriptor and then jump to it in 680x0 code. The drd 
demd in MacsBug will let you see this routine descriptor 
in a meaningful way. When I typed drd pc in this case, 
I saw the contents of Listing 1. 
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Listing 1 * Displaying a routine descriptor 
drd: 0G167fcc 

MixedModeMagic: GxAAFE, version: #7, flags: 0x00 (NotlndexableJ 

LoadLoc: 0x00000000, reserved2: 0x00000000, Selectorlnfo: 0x00 (No Selector) 

Routine Count (zero-based): 0x0000 (#0) 

- Routine Record 0x0000 (#0) at 0xQQ167fd8 —— 

Proclnfo: 0x00003002 r Reservedl: 0x00000000, ISA: #1 (PowerPC) 

Record Flags: 0x0004 {Absolute, IsPrepared, NativelSA, PassSelector, IsNotDefault) 
ProcPtr: 0x00078274, offset: 0x00000000, selector: 0x00000000 


Notice the number of fields displayed in Listing 1, For 
simple routine descriptors like this one, you'll only need to 
look at the ProcPtr entry on the last line of the display. More 
complicated routine descriptors have an array of routines, and 
you'll need to look for a passed selector to determine which 
one is actually used.* 

The hist line of the listing shows a ProcPtr value of 
$00078274, This is the address of the TVector for 
MaxApplZone in the MeinoryMgr code fragment. 
Since the TVector structure has die routine address as 
its first element, dereferencing that address once will 
produce the address of the actual routine. Typing ilp 
@78274 to dereference the TVector and disassemble 
PowerPC code showed me this: 

_MaxApplZone 


+00000 

OOOCA1A8 

mf lr 

r0 

+00004 

OOOCA1AC 

stwu 

SP,-0x0040(SP) 

+00008 

OQ0CA1B0 

stw 

r0,0xQ048(SP) 

+00Q0C 

OOOCA1B4 

bl 

_HSetStateQ+Q073C 

+00010 

QQ0CA1B8 

ermove 

cr7_SO,cr7_SO 

+00014 

OOOCA1BC 

extsh 

r4,r3 

+00018 

OOOCA1CO 

li 

r3,0x0000 

+0001C 

OOQCA1C4 

bl 

SetEmulatorRegister 

+00020 

OOOCA1C8 

Iwz 

RTOC , 0x0014(SP) 

+00024 

OQ0CA1CC 

lwz 

r!2,0x0048(SP) 

+00028 

QOOCA1DO 

addic 

SP,SP,0x0040 

+0002C 

0Q0CA1D4 

mtlr 

r!2 

+00030 

OOQCA1Q8 

blr 



This is the MaxApplZone routine in the Memory 
Manager, It appears to call more substantial subroutines 

when it branches to_HSetStateQ+0073C, but this is 

the actual routine, 

WALKING BACK OUT 

WeVe braved routine descriptors, glue* and patches to 
make it this far. I won’t dive further into the Memory 
Manager for this illustration, but let’s try an instructive 
walk back out from the MaxApplZone routine. 


After tracing through this routine, we step over the blr 
instruction to branch back to the link register address. 
To our surprise we not only switch back to 680x0 
emulation mode but we appear to be lost in darkness. 
The following 680x0 F-line instruction will be executed 
next: 

No procedure name 
OI62DOAO DC.W $FE02 

We switched back to 680x0 emulation mode because 
weVe returning from the 680x0 patch call to a routine 
descriptor. Typing ip to disassemble at the current 
location shows what appears to he garbage, however: 

No procedure name 


0162DOBC 

NEGX.L 

D7 

0162D03E 

EOR.W 

D3,(A0)+ 

0162D090 

BCHG 

DO,-(A2) 

0162D092 

DC.W 

SDOFO 

0162D094 

DC.W 

5FFFF 

0162D096 

ORI.B 

#SOO,D4 

0162D09A 

DC.W 

$FFFF 

0162D09C 

ORI.B 

#$A063,D0 

0162DOAO 

*DC. W 

SFE02 

0162D0BC 

NEGX,L 

D7 

0162DOBE 

EOR.W 

D3,(A0)+ 

0162D090 

BCHG 

DO, - (A2) 

0162D092 

DC.W 

$D0FD 

Q162D0A2 

ORI.B 

»$9C,DQ 

0162D0AS 

BCLR 

DO, D 3 

0162D0AB 

BCHG 

D0,-(A2) 

0162DOAA 

ADD.B 

DO,(AO) 


I Iere’s the secret: The $FE02 F-line instruction is very 
much like the _MixedModeMagic trap in that it can 
signal the transition from emulated 680x0 code to 
PowerPC code. Just as with the routine descriptor that 
we saw earlier, executing the $FEG2 instruction will in 
this case cause us to switch back to PowerPC native 
mode and will bring us to a completely different 
address. 
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Listing 2* The stock upon return to PowerPC code 
Displaying memory from sp 


Q162DQ80 

DDOD 

ODDD 

DDDD 

DDDD 

7FFF 

7FFF 

4087 

B750 

-t * - * - 

0162D090 

0162 

00 FQ 

FFFF 

0004 

0000 

FFFF 

0000 

A063 

£x-b- 

0162D0A0 

FE02 

0000 

009C 

0183 

0162 

duo 

oooo 

3802 

tc* * * * 


Truly perceptive readers might have noticed that the 
program counter at the $FE02 instruction is actually 
on the stack. Listing 2 shows a memory dump of the 
first 48 bytes of the stack at this time. Notice that the 
word at the beginning of the third line {at S162D0A0) 
is the $FE02 instruction we’re about to execute. 

As we trace over that $FEG2 instruction, we find 
ourselves back inside the InterfaceLib glue routine for 
MaxApplZone. Tracing through those last instructions 
finally takes us back to the application code where we 
started* as shown here: 

MaxApplZone 


+0Q02Q 

40A0E32C 

Iwz 

RTOC,0x0014(SP) 

+00024 

40AOE330 

lwz 

rl2,0xO048(SP) 

+DG02B 

40A0E334 

addic 

SP,SP,0x0040 

+0002C 

40A0E338 

mtlr 

r!2 

+00030 

40A0E33C 

blr 



No procedure name 

0093B280 lm RTOC, 0x0014 (SP) 

G093B284 li r31,0x0001 

Notice that when we returned to a previous code 
fragment, we immediately restored the TOC register 
to a value saved on the stack. Not only is the caller 
responsible for setting the TOC register before calling 
a routine, it’s also responsible for restoring this register 
when the call returns. 

This concludes our romp through the wilderness of the 
modern PowerPC environment. We traced from an 
application’s code fragment, through the InterfaceLib 
fragment and then a patch in the trap table, to a routine 
descriptor for the real MaxApplZone routine, and 
ultimately back again, 

CATCHING POWERPC CALLS 

Earlier I glossed over how to set a breakpoint and catch 
an application as it calls MaxApplZone. Now FU describe 
a good trick for doing this. 

The MacsBug debugger doesn't implement 680x0 
A-trap break commands for PowerPC code yet. But you 
can easily mimic the A-trap break feature in PowerPC 
code, using the FindSym, PlayMem, and PPCJump 


MacsBug macros. You can use those macros if you 
install the file “PowerPC dcmds" {which you’ll find on 
this issue’s CD) into your MacsBug Preferences folder. 

Say, as an example, that you’d like to catch all PowerPC 
code that calls the Toolbox routine ReleaseResource. 
PowerPC code fragments access this routine by 
importing its entry point from the InterfaceLib code 
fragment. Typing FindSym ReleaseResource on my 
PowerMacintosh 8100 produces the following: 

findsym: "ReleaseResource" 

"ReleaseResource" #1796 TVec QOOlaccG 
(40al597B,0001eal4) in "InterfaceLib" 

FindSym is case sensitive. When looking for on entry in 
interface lib, for example, you must spell the routine name 
exactly and capitalize letters perfectly; typing "re lease resource" 
rather than "ReleaseResource" will not work, * 

This tells us a fe w things. Release Resource’s 1 Vector 
is located at the address SOOOIACCO. That vector 
contains the address for the routine at S40A15978 and 
the InterfaceLib^ TOC value, which is S0001EA14. 
FindSym will return TVector addresses for each 
application or fragment bound to the routine. In 
System 7 these will usually all be the same TVector, 

If I need to catch callers to ReleaseResource, I could 
then simply type brp 40a 15978 to set a PowerPC 
breakpoint at the beginning of die InterfaceLib code. 
On the Power Macintosh 8100, however, tills address is 
in ROM. Setting breakpoints in ROM is more difficult 
for MacsBug, which returns tills message: 

Warning: This requires stepping through each 
instruction 

Your Macintosh might become unusable if MacsBug is 
forced to single-step through all the code. Because 
MacsBug can set a breakpoint in RAM with less 
difficulty; we’ll now use the PlayMem and PPCJump 
macros to set an equivalent breakpoint in RAM. 

PlayMem is a MacsBug variable that points to 512 bytes 
of scratch memory in RAM. The PPCJump macro 
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expands to a set of PowerPC instructions for jumping 
to an absolute address. So the command 

si PlayMem FPCJump 4Gal5978 

writes the following instructions to xMacsBug’s scratch 
memory; 

lis r0,40al | 3C004GA1 

or! r0|rO,5978 | 60005978 

mtctr rO j 7C0903A6 

bctr | 4E800420 

Now I’ll replace the value of the TVeetor with our new 
code in scratch space, by typing si OOOlaccO PlayMem. 
PowerPC code bound with InterfaceLib will now call 
my new code instead of ReleaseResource, but my code 
will then correctly pass control to ReleaseResource. 


Finally typing brp PlayMem will set the PowerPC 
breakpoint wc want. 

When PowerPC code tries to call the ReleaseResource 
trap via InterfaceLib, execution will stop at my 
breakpoint in PlayMem. At that point, typing ipp lr 
will list PowerPC instructions around the address in 
the link register, quickly showing me which code was 
calling the trap. 

AFTER THE HUNT 

Although I seriously doubt I would find enjoyment in 
hunting live animals, I’ve found the hunt for software 
defects truly rewarding. Some problems are a definite 
challenge, and I often learn something new about the 
Mac OS with each riddle solved. 1 hope that knowing 
die derails of my pursuit will help you in your own 
future quests. 


Thank s to Nrfirt Ganatra, Pete Gonfier, Jim Luther, and Alex Rangel 
for reviewing this column. * 
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Game Controls for QuickDraw 3D 


Whether the user is navigating a starship or examining a model of the 
DNA helix, your first-person 3D application must allow user control of 
the camera movements in a scene. You must keep changing the camera's 
position and orientation in response to what the user wants to see. Here 
you'll learn how to create those camera movements and handle the user's 
directions. As part of the bargain, you 'll even get a refi'esher course in 
the associated geornetry. 



PHILIP MCBRIDE 


Letting the user control the movement of the camera (and thus the view) is critical 
to first-person interactive 3D games and extremely useful in 3D modeling systems* 
Through QuickDraw ID’s camera functions and supporting mathematical functions, 
you can create game controls that direct the position and orientation of a camera. In 
general, game controls take user input from any input device and control the camera 
in ways that emulate movements of players, such as people or aircraft* Game controls 
are useful for any type of 3D viewer application, including 3D Internet browsers* 

You'll start your career as a camera operator by learning about die basic moves you 
can make with the camera. Then you’ll create the various camera movements, keep 
the camera movements smooth, and translate user inputs to move the camera. The 
sample code (which is provided on this issue’s CD) is a 3D viewer application with 
camera movements activated by the keyboard or the mouse* In all ol the code, the 
geometry has been kept as simple as possible, but if you need to brush up, you’ll find 
a refresher course on calculating points and vectors in 3D space* 


For an overview of QuickDraw 3D, turn to “QuickDraw' 3D: A New Dimension for 
Macintosh Graphics” in develop Issue 22. That article discusses topics like reading 
models, using a viewer, creating a camera, and managing documents that have 3D 
information. To learn more about those and related topics, see the list of recommended 
reading at the end of this article. 


MOVING THE CAMERA 

We’ll be controlling camera movements based on first-person view ing, so the camera 
will be our eyes. But before we move through a scene, let’s take a look at the kind oi 
camera moves we plan to use. 


PHILIP MCBRIDE (mcbrtde@apple r com) is 
currently adding QuickDraw 3D and QuickTime 
VR to HyperCard 3.0. He used to spend time 
contemplating the meaning of the universe until 
he figured it out. Now he can be seen wandering 
the halts at Apple and mumbling something about 


needing more content. Lately Philip has been 
looking into investing in anteaters after learning 
that a full 20% of the earth's biomass is made up 
of ants and termites. Just think about that 
overcrowding the next time someone says we 
don't need to invest in space travel. J 
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The camera movements you would create in a 3D game for a person who is driving a 
vehicle or walking on level ground are examples of ground movements. These camera 
moves include moving forward, backward, sideways to the left, and sideways to the 
right, plus turning to the left (pan or yaw left) and turning to die right (pan or yaw 
right). Figure 1 illustrates these basic ground movements. 



Figure 1 • Ground movements 

You can also go airborne with a variety of camera movements. These fancier camera 
moves are changes that might he typical of an aircraft. They include ascending and 
descending (moving upward and downward), pitching (tilting) up and down, and 
rolling (tilting) left and right. Figure 2 illustrates these moves. 



Ascend 


Pitch up 



Pitch down 


Figure 2. Air movements 


Now to the fun part — let’s get that camera moving! What you must do to achieve 
the previously described camera movements, both ground and air, involves some 
geometry. If you’re like most of us and have forgotten your 3D geometry, see “3 D 
Geometry 101” for a refresher course. The 3D geometry for our camera moves is 
quite simple; it will stick to die kinds of calculations illustrated in “3D Geometry 
101 ." 

First, let’s take a look at our world. In Figure 3, we have an object in the world 
coordinate system and a camera looking at the object. The camera has its own 
coordinate system defined by its location (in world coordinates), up vector, and point 
of interest. 

We’ll he dealing with the vectors making up the camera’s coordinate system for many 
of our movement functions, so let’s keep these in our application’s document 
structure. We’ll keep the camera placement data there as well. 

The document structure looks like this: 
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typedef struct DocumentRecord { 


TQ3Point3D 
TQ3Foint3D 
TQ3Vector3D 
TQ3Vector3D 
TQ3Vector3D 


earner allocation; 
pointOfInterest; 
xVector; 

yVector; //up vector 

z Vector; 


} DocumentRecord, *DocumentPtr; 

The first time we set up our camera, well set the values in our document to correspond 
to the initial camera position. Then with each subsequent movement of the camera, 
we’ll update these fields. The initial camera data is constructed by the code in Listing 
1. In the function MyGetCaineraData, we do some of our geometric calculations to 
get the x and z vectors. We subtract the two endpoints (the initial and final points) of 
the z vector to get that vector. And we get the x vector by cross-multiplying the y and 
z vectors. 


Listing 1* Initializing the camera data 

void MyGetCameraData(DocumentPtr theDocument, TQ3Camera0bject theGamera} 

{ 

T Q 3C ame r aP1acement c ame r aP1ac erne nt; 

// Get the camera data. 

Q3Camera_GetPlacement(theCamera, frcameraPlacement); 

// Set the document's camera data. 

theDocmnent->cameraLocation = earneraPlacament.cameraLocation; 
theDocument->pointOfInterest = cameraPlacement,pointOfInterest; 
theDocmnent->yVector = earneraPlacement♦upVector; 

// Calculate the x and z vectors and assign them to the document. 

Q3Point3D_Subtract(&theDocument->pointOfInterest,StheDocument->cameraLocation, 
StheDocument->zVector]; 

Q3Vector3D Cross(&theDocument~>zVector, & theDocument~>yVector, &theDocument->xVector); 
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3D GEOMETRY 101 

If you're new to 3D programming [and perhaps a little 
rusty on your math), here's a brief Introduction to some of 
the 3D concepts you'll find in this article's code, 

A point is represented in 3D space by x, y, and z values 
in a coordinate system, A vector is a magnitude (length) 
and direction; it's represented by an initial point [usually 
the origin of the coordinate system) and a final point 
{x, y f z). Figure 4 illustrates a point and a vector in 3D 
space. 


y 



To add a vector and a point, you place the vector's initial 
point on that point (keeping the vector's direction and 
magnitude). The new final point of the moved vector is the 
point resulting from the addition. (See Figure 5.) 


i 



Figure 5. Adding a vector and a point 


To subtract a vector from a point, you place the vector's 
final point on that point (keeping the vector's direction 
and magnitude). The new initial point of the moved vector 
is the result (Figure 6). 

V “ Point p 


i 

i 

i 



Figure 6. Subtracting a vector from a point 

To create a vector between two points, you subtract the 
vectors defined by the points (called position vectors). To 
do this, you first reverse (turn around) the second vector 
and place its initial point on the final point of the first 
vector. Then you make a new vector from the first vector's 
initial point to the second vector's new final point. This 
new vector has the direction and magnitude of the vector 
between the two points (Figure 7). 



Figure 7* Creating a vector between two points 
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A translation of a point or o vector by J Xf T yj and T z 
values moves the point or the vector by adding the T 
values to its own values (Figure 8). 



Figure 8. Translating a point or a vector by T 

In Figure 8, the translation value T is really From the 
translation part of a transformation matrix. A transformation 
matrix is used to transform a point or a vector by 
translation, rotation, and scaling. The transformation 
matrix you use is 4 x 4 — with the upper-left 3x3 
portion acting as the rotation matrix, the bottom-left 1 x 3 
portion acting as the translation matrix, and the top-left to 
bottom-right diagonal of the rotation matrix acting as the 
scaling matrix. The following transformation matrix has 
elements labeled for translation |T], rotation |tf), and 
scaling (5). The fourth column is ignored for simplicity. 


V R o,o 

R 0,l 

R 0,2 

1 

0 

P l,0 


R 12 

0 

R 2,0 

^2,1 

S z* R 2,2 0 [ 

r x 

T y 

r z 

i 


When you apply a transformation to a point or a vector, 
you multiply by the matrix, as in the following formula for 
our point (x, y f z} and a transformation matrix: 

[{$ x *fl 0 ,O* x + *1,0*/ + R 2,Q* z + U 
[R Q] *x + S y *R lt] *y + + T yh 

(ff 02 * x + *1,2*/ + S z *R 2i 2* z + yi 

As you can see from this Formula, if you only want the 
matrix to apply a translation (the T's), the 3 x 3 rotation 


matrix will be all G's except for the scaling diagonal, 
which will be all Ts. 

A rotation of a vector through an arbitrary angle about 
different axes will use various R elements (the 3x3 
rotation matrix of the transformation matrix), depending 
on which axis you're rotating about. For rotations of 0 
about the x axis, you get the matrix 

I 1 ° 

<0 cos e 

) 0 -sin B 

For rotations about the z axis, you get 

( cose sine oj 

-sin 8 cos 8 0 > 

0 0 ij 

And for rotations about the y axis, you get the following 
matrix: 

( cos 8 0 -sine! 

0 10 

sin 8 0 cos 6 

So to apply a rotation about an axis, you simply multiply 
the appropriate rotation matrix by the vector. In Figure 9, 
the vector on the right is rotated 90° about the z axis in 
the {x, y) plane. 

Rotate 90* about z 



Figure 9. Rotating a vector about an axis 


0 1 
sm 8 > 

COS 0 
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After the fields in our document have been updated by some camera movement 
function, we'll want to reset die camera to that new data with the function 
MySetCameraData (Listing 2), 


Listing 2. Setting the camera data after a move 

void MySetCameraData(DocumentPtr theDocument, TQSCameraObject theCamera) 

{ 

TQ3GameraPlacement earneraPlacement \ 

// Set the camera placement data, 

earneraPlacement,earneraLocation = theDocument->cameraLocation; 
earneraPlacement,pointOfInterest = theDocument->pointOfInterest; 
cameraPlacement,npVector = theDccument->yVectorj 

// Set the camera data to the camera, 

Q3Camera_SetPlacement[theCamera, ReameraPlacement}; 


With that camera infrastructure, we're ready to move the camera around a bit. 

You can find the code for all the moves on this issue's CD, Here you’ll find only the 
code for those movements that are unique. Code for those moves not shown (but 
previously mentioned) is almost identical to one of the functions shown in the 
listings. 

To move the camera along the z axis either forward or backward, we call the function 
MyMoveCameraZ (Listing 3). This function translates the camera location and point 
of interest by the given delta. Note that die associated z vector isn’t changed. 

To move the camera along the x axis (right or left) or along the y axis (ascending or 
descending), you use code similar to Listing 3, The only difference is that you base 
the translation on the change in .r or y instead of the change in s. In both cases, the 
associated vectors don't change. 

Next, to rotate the camera right or left about the y axis, we call the function 
MyRotateCameraY (Listing 4), This function first creates a transformation matrix 
whose rotation matrix represents rotating about the y axis. It then transforms both 
the z and * vectors by that rotation (thus rotating those two vectors about the y axis). 
From the rotated z vector, we obtain the point of interest by adding the camera 
location to the vector. 

Rotating the camera about the x axis (pitching up or down) or about the z axis (rolling 
left or right) is similar to rotating it about the y axis. The main difference is in how the 
rotation matrix is constructed (from the axis in question) and which axes are rotated (the 
other two). The only other difference is that when rotating the camera about the z axis, 
you don't have to update the point of interest because it doesn’t change. 

SMOOTH SAILING 

To see what we’ve done to our world, we need a rendering loop, which you'll find in 
the code on the CD. Since we don't do anything special in our rendering loop, ive’U 
skip the details. For an explanation of rendering loops, see the article “QuickDraw 
3D: A New Dimension for Macintosh Graphics" in develop Issue 22. 
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Listing 3, Moving the camera along the zaxis 


void MyMoveCameraZ(DocumentPtr theDocument, float dZ) 


TQ3View0bject 

TQ3Camera0bject 

TQ3Vector3D 

TQ3Point3D 


theView; 
theCamera; 
scaledVector; 
newPoint; 


// Get the view and the camera objects, 
theView = theDocument->theView; 

Q 3 View^GetCamera(th e Vie w # &the C ame r a); 

// Scale the y vector to make it dY longer. 

Q3Vector3D_Scale(&theDocument“>yVector, 

dY/G3Vector3D_Length {&theDocument->yVector), 6 scaledVector); 

// Hove the camera position and direction by the new vector. 
Q3Point3D_Vector3D Add(&theDocument->cameraLocation , & s caledVector, 
SnewPoint); 

theDocument->cameraLocation = newPoint; 

Q3Point3D_Vector3D_Add(&theDoctiment->pointOf Inter est, & scaledVector , 

&newPoint); 

theDocument->pointOfInterest = newPoint; 

// Set the updated camera data to the camera. 

MySetCameraData(theDoeument , theCamera); 

// Update the view with the changed camera and dispose of the camera. 
Q3View_SetCamera(theView, theCamera); 

Q 3 Ob j e ct Dispos e{theC amer a); 


Listing 4, Rotating the camera about the / axis 


void MyRotateCameraY(Document?tr theDoeument, float dY) 


TQ3ViewQbject 
TQ 3 Camer aOb j ec t 
TQ3Vector3D 
TQ3Matrix4x4 


theView; 
theCamera; 
rotatedVector; 
rota tio nMat r i x; 


// Get the view and the camera objects. 
theView » theDocument~>theView; 

Q3View_GetCamera(theView, stheCamera); 

// Create the rotation matrix for rotating about the y axis. 
G3Matrix4x4_SetRotateAboutAxis(SrotationMatrix, 

&theDocument“>cameraLocation, &theDocument->yVector, dY); 

// Rotate the z vector about the y axis. 

Q3Vector3DTransform(StheDocument->zVector, irotationMatrix, 
&rotatedVector); 


(continued on next page) 
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Listing 4, Rotating the camera about the yaxis (continued) 
theDacument-> 2 Vector = rotatedVector; 

// Rotate the x vector about the y axis. 

Q3Vector3D_Transform(stheDocument->xVector, srotationMatrix, 

&rotatedVector ); 

theDocument->xVector = rotatedVector; 

// Update the point of interest from the new z vector* 
Q3Point3D_Vector3D_Add(&theDocument->cameraLocation, 

&theDocument->zVector, &theDocument->pointofInterest)j 

// Set the updated camera data to the camera. 

MySetCameraData(theDocument , theCamera); 

// Update the view with the changed camera and dispose of the camera. 
Q3View_SetCamera(theView, theCamera}; 

Q30bject_Dispose(theCamera); 


The real issue for us in viewing our camera movements is how smooth and fast those 
moves appear. The factors that determine how r smoothly and quickly the moves work 
are the sizes (scales) of the deltas (the arguments to the movement functions) and the 
speed of the machine {and therefore the subsequent speed of the rendering loop). 
Adjusting for the speed of the machine is beyond the scope of this article. 

The sizes of die deltas determine the size of the jumps taken by each camera movement. 
If the deltas are very small, the camera will move very slighdy. And if these movements 
are repeated, the camera will appear to move slowly over time. If the deltas are large, 
the camera will appear to move fast. 

If you move the camera too slowly, the movement will appear jumpy because the user 
will see the delays in rendering time. If you move the camera too fast, the movement 
will appear jumpy because, well, you’re making the camera take big jumps. To find 
just the right speed, you need to experiment with the sizes of the deltas. The main 
thing to notice is that you should correlate the deltas to the size of the model. 

Listing 5 shows how you might set up the delta multipliers (called fact&rs here) 
that are used to help control movement From the model's bounding box, the 
MylnitDeltaFactors function determines the size of the largest dimension. This 
model size is then used to generate the various factors for different movement 
functions. Since accelerating the movements (say, by a control key) is quite useful, 
this function sets that up too. 

Your mileage may vary, so it's a good idea to take your camera out for a spin and see 
what factors work for your application. 

CONTROLLING THE CONTROLS 

Now that you have the means of moving the camera this way and that, you need to 
have something controlling those movements. Our application will use the keyboard 
and the mouse. 
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Listing 5. Creating delta Factors based on the model's dimensions 


void MylnitDeltaFaotors(DocumentPtr theDocument) 


TQ3BoundingBox 

TQ3Vector3D 

float 


viewBBox; 

diagcmalVector? 

maxDimension; 


// Get the bounding box and find the scene dimension. 
MyGetBoundingBox{theDocument, &viewBBox); 

Q3 Point 3 D_Subtract{&viewBBox„max , & viewBBox.min, &diagonaIVector); 
maxDimension = Q3Vector3D_Length(sdiagonalVector); 

H Now set the delta factors. 

theDocument->xRotFactor * kXRotFactorBase * maxDimension; 
theDocument->yRotFactor = kYRotFactorBase * maxDimension; 
theDocument->zRotFactor - kZRotFactorBase * maxDimension; 
theDocument->xMoveFactor - kXMoveFactorBase * maxDimension; 
theDocument*>yMoveFactor - kYMoveFactorBase * maxDimension; 
theDocument->zMoveFactor = kZMoveFactorBase * maxDimension; 

// Set up the control factor. 

theDocument->controlFactor = kControlFactorBase * maxDimension; 


To take input from the keyboard or the mouse, or both, we don't do anything unusual. 
For the keyboard, we take the key-down events as they happen and determine whether 
any other keys were held down at the time of the event (for multiple key inputs). For 
the mouse, we just continually track it. 

In both cases, the user can indicate movement along more than one dimension. For 
example, if moving the mouse forward means “forward" and moving the mouse left 
means a combination of “turn left” and “roll left,” a mouse movement that's both 
forward and to the left is a combination of three camera movements. 

Based on whether the user input is simple or complex, our code makes calls to the 
appropriate camera movement functions. In the case of the mouse, the speed of the 
mouse (the difference between the last position and the current position) is also used 
to adjust the deltas for the camera movement. Listing 6 shows the code used for 
mouse tracking, but without the error handling and some details of GWorlds and 
local coordinates (see this issue's CD for the full source code). Here we’ve hard coded 
the meanings of the different mouse movements and control keys for simplicity. 
Ideally, you would have this stored in preference data that the user can set. 

The code for handling keyboard input is even simpler. See the CD for that part of the 
code. 

Many other input devices are also applicable, especially 3D input devices. The proper 
way to handle such input devices is through the QuickDraw 3D Pointing Device 
Manager with its controllers and trackers. To use this approach, we would need to 
define a tracker for our camera and assign it to the avadable controllers. We would 
also change the camera movement functions so that they took deltas of both position 
and orientation. See the book 3D Graphics Programming With QuickDraw 3D and the 
Graphical Truffles column “Making the Most of QuickDraw 3D" in develop Issue 24 
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Listing 6. Tracking the mouse 

void MyDoMouseMovefWlndowPtr theWindow, EventRecord *theEvent) 

{ 

Do cumentPt r the Doc ume nt; 

Point newMouse; 

long dx, dy, oldX, oldY; 

float xRot , yRot; 

short usingControl = false; 

// Get the document from the window. 
theDocument = MyGetDocumentFromWindow(theWindow }; 

// Get the current mouse position. 

GetMouse(&newMouse); 
oldX = newMouse.h; 
oldY = newMouse.v; 

// If the control key is down, we're in depth mode, 
if (theEvent->modifiers & controlKey) 
usingControl » true; 

// Loop, moving the camera while the mouse is down, 
while (StillDown()) ( 

// Get the next mouse position. 

GetMouse(£newMouse); 

// Calculate the difference from the last mouse position, 
dx = newMouse.h - oldX; 
dy = oldY - newMouse.v; 

// If there’s some difference, move the camera, 
if ((dx 1 * 0 ) || (dy != 0)) { 

// Calculate the rotation about the y axis (pan) and rotate. 
yRot - ((float) dx * (kQPi / 130.0)) / theDocument->width; 

MyRot a te C ame raY(t heDo c umen t, -yRot * t h eDoc ume nt->yRot Factor); 

// If the control key is down, move along the z axis; otherwise, rotate about the x axis, 
if (usingControl) { 

// Move the camera along the z axis (change in mouse’s y)» 

MyMoveC ame r aZ(t h e Document, dy * the Documen t-> zM ove Fa ct or); 

1 else { 

// Calculate the rotation about the x axis (pitch) and rotate. 
xRot = ((float) dy * (kQPi / 1BO.O)) / theDocument->height; 

MyRot a te C ame r aX(t h eDoc ument, x Rot * t he D oc ume n t- > xRot F ac tor); 

> 

// Update the screen for each move. 

MyUpdateScreen(theDocument); 

> 

// Set the current mouse position as the old mouse position for the next update. 
oldX = newMouse.h; 
oldY - newMouse.v; 

} 

} 
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for more on controllers and trackers. (As of now, QuickDraw 3D doesn't have built- 
in controllers for the mouse and the keyboard, so this code handles them directly.) 

AIMING FOR EFFICIENCY 

To make the geometry and the code for this article clearer, some efficiency issues 
were ignored. But for most applications, the time spent in moving the camera will be 
minimal when compared to the time spent rendering and displaying each frame. 

How ever, if the time used for the rendering-rastering phase is minimal and the camera 
movements use a more significant percentage of the total time, there are a number of 
solutions. The ultimate efficiency solution is to avoid making any multiplications or 
divisions in the camera movements by using finite differencing techniques when 
calculating the moves. This strategy involves keeping more information about each 
intermediate change and making only the incremental calculations necessary for the 
next move. This approach is similar to operator reductions in compilers. 

MAKING YOUR NEXT MOVE 

A number of applications can use game controls like those discussed here, not just 
first-person 3D games. Another application that’s a good candidate for the kinds of 
game controls presented here would be a 3D Internet browser. You would w r ant 
similar 3D controls, but you would also want some controls for selecting Web hot 
spots that would take you to another 3D Web site. 

So now the next move is up to you. 


RECOMMENDED READING 

* "QuickDraw 3D: A New Dimension for Macintosh Graphics" by Pablo Fernicoh 
and Ntck Thompson, develop Issue 22. 

* "Graphical Truffles: Making the Most of QuickDraw 3D" by Nick Thompson and 
Poblo Fernicola, develop Issue 24. 

* 3D Graph/es Programming With QuickDraw 3D by Apple Computer, Inc. (Addison- 
Wesley, 1993). 

* Mathematical Elements for Computer Graphics, 2nd Edition, by David F. Rogers 
and J. Alan Adams (McGraw-Hill, 1990). 

* Tr/cfcs of the Mac Game Programming Gurus by Jamie McCornack and others 
[Hayden Books, 1995). 
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DANIEL I. UPTON 


A Library for 
Traversing Paths 


The QuickDraw GX graphics system is based on shape 
objects that are used by reference. An application 
creates a shape object such as a path or a polygon by 
passing in data that represents the geometric points of 
the shape to be drawn or otherwise manipulated The 
QuickDraw GX graphics system then stores this 
information in its internal database and returns to die 
application a reference to the shape object. This 
reference is then passed to the various QuickDraw GX 
routines that perform operations on the shape. 

Since die QuickDraw GX graphics system is maintaining 
the original data in its database, the application often 
won’t keep this data around. AJso, an application may 
not even have created die geometric points in the first 
place, as in the case of converting text into a path. 


Point 2 (off curve) 



Point 1 (on curve) 


Point 3 (on curve) 


Figure 1. A QuickDraw GX quadratic curve segment 


points. The object can contain multiple contours, each 
contour being a group of connected segments. 

The question arises, if we look at a specific point in a 
path structure, whether the point is part of a line 
segment or part of a curve segment. The answer is that 
in addition to the points themselves, a path contains an 
array of flags, one for each point, indicating whether 
the point is on or off the path, lb represent a single 
contour for a path object, QuickDraw GX uses the 
gxPath data structure: 

struct gxPath { 

long vectors; 

long controlBits[1]; 

struct gxPoint vector [ 1]; 

}f 

typedef struct gxPath gxPath; 


Ids often desirable, for a variety of purposes, for an 
application to retrieve the geometric information from 
a shape object. Given the richness of geometric 
information that these objects can contain, it can be a 
nontrivial task to read hack the information. This 
column describes a C library that any application can 
incorporate for the purpose of traversing the geometric 
information in QuickDraw GX paths. 

WHAT'S IN A QUICKDRAW GX PATH OBJECT 

The QuickDraw GX graphics system provides several 
types of graphics primitives with which to create visual 
content: lines, curves, polygons, paths, typography, and 
bitmaps. In this system, curves are quadratic Beziers 
that can be defined by three control points, the middle 
point being off the curve and the other two being on. 
Figure 1 depicts a single quadratic curve segment. 

A QuickDraw GX path object is just a conglomeration 
of curve and line segments, resulting from an array of 


The vectors field is an integer that specifies die number 
of points in the contour, the control Bits field is a bit 
array representing the on-curve/offrcurve flags, and the 
vector field is an array of points for the contour. 

To represent a path object, QuickDraw GX uses the 
gxPaths data structure: 

struct gxPaths { 

long contours; 

struct gxPath contour[1]; 

>? 

typedef struct gxPaths gxPaths; 

The contours field is an integer specifying die number 
of contours, and the contour field is an array of gxPath 
structures, one for each contour. 

Hence we have enough information to figure out what 
the points mean. If we see two on-path points in a row, 
we know that represents a line. If we see an on-path 


DANIEL L UPTON (danlelJipton@powertalkapple.com] has QuickDraw GX team members. In his spare time, Dan runs a small 

worked af Apple for seven years and is one of the original business repairing perpetual motion machines, * 
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point followed by an off-path point followed by an on- 
path point, we know that’s a quadratic curve segment. 

So to read the QuickDraw GX path object to determine 
the actual shape, all we have to do is get a point and 
then get the next point. According to the previous 
description, it would be safe to assume that die very 
first point in a contour is an on-path point. Then, if the 
next one were also on the path, we’d have a line; if it 
were off, we’d know that we’d have to read a third one 
(which by definition would have to be on) and we’d 
have a curve. 

The only trouble is that those assumptions aren’t 
necessarily true. The design of QuickDraw GX could 
have restricted applications to using only those patterns 
of on-path/off-path points, disallowing two consecutive 
off-path points and requiring the first point and the last 
point in a contour to be on the path; however, it didn’t. 

In the interest of saving memory, QuickDraw GX 
allows two consecutive off-path points to imply a middle 
on-path point — known as an implicit point — exactly 
halfway between the off-path points. An example of this 
is shown in Figure 2. 


Point 4 (on curve) 



Figure 2. A QuickDraw GX quadratic path 

For each implicit point there’s a memory savings of 
8 bytes in QuickDraw GX. This allows us to define 
geomemes in less space than would be required in 
other popular graphics models that use cubic Bezier 
curves without implicit points, hut it does complicate 
traversing the path. 

QuickDraw GX also allows die first or the last point of 
a contour to be off the curve, in the case where the 
contour is closed. This further complicates path 
traversal. 


THE SHAPEWALKER LIBRARY 

You can use the Shape Walker library {which is included 
on this issue’s CD) to avoid having to write a huge blob 
of code to deal with all those points and flags discussed 
above. It allows an application to pass in a QuickDraw 
GX shape object and be sent back (via callbacks) each 
line and curve segment in the shape. All implicit points 
are resolved by the library so the client sees only 
complete line or curve segments. 

The header file to be used with the library defines types 
for four callbacks and a prototype for the Shape Walker 
function: 

// Function is called to move to a new point 
// (start new contour), 

t ypedef Boolean (*TpwMovetoProc ) (g xP o i n t * p , 
void* refcon); 

it Function is called to draw a line from 
tf current point to p. 

typedef Boolean (*TpwLinetoProc)(gxPoint *p, 
void* refcon); 

// Function is called to draw a curve from 
if current point (which will be p[0]) through 

n pti] to p[2j. 

typedef Boolean (*TpwCurvetoProc)(gxPoint p[3] f 
void* refcon}; 

// Function is called to close a contour, 
typedef Boolean (*TpwClosepathProc) 

(void* refcon}; 

// Return result will be true if path walking 
// was terminated by one of the callbacks. 

Boolean ShapeWalker(gxShape theShape, 

TpwMovetoProc DoMoveto, 
TpwLinetoFroc DoLineto, 

TpwC u rveto P roc DoC u rve to, 
TpwClosepathProc DoCiosepath, 
void* refcon); 

When using die library, you provide four callbacks and 
a refcon. Each callback will get passed the refcon and 
possibly point information. It’s suggested that the client 
maintain whatever state information is necessary for 
the purpose at hand. The refcon can be a pointer to a 
structure containing the state information. One typical 
component of such information that most clients would 
need is the notion of the current point. The current 
point is the piece of the path we’ve looked at most 
recently, representative of the state of processing the 
shape. Tlus current point should be updated as segments 
come through the callbacks. (We’ll see this in a moment 
in our sample application.) 
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Each callback must also return a result of type Boolean, 
giving the client a mechanism for causing the library to 
terminate traversal of the shape before completion. 
Return false and the shape walker will continue on to 
die next segment; return true and it will terminate 
early. This can be used to catch errors in processing the 
points, or to terminate processing if youVe finished 
with the shape before the last point is reached. 

The four callbacks are as follows: 

# DoMoveto — This procedure is called at the start of 
each new contour in the shape. It gets passed a 
single point and the refcon. The point identifies the 
location of the beginning of the contour. If the client 
is maintaining a current point via the refcon, it 
should be updated to the point passed in. 

• DoLineto — This procedure is called for each line 
segment in the contour. It gets passed a single point 
and the refcon. The point represents the end point 
of the line segment. The start point of the line 
segment is whatever point we last saw; that will be 


the current point if one is being maintained. If the 
client is maintaining a current point via the refcon, it 
should be updated to the point passed in. 

* DoCurveto -— This procedure is called for each 
quadratic curve segment in the contour. It gets passed 
an array of three points and the refcon. The three 
points correspond to the control points of the curve. 
The first point in the array will be the current point 
if one is being maintained. The current point should 
then be updated to reflect the third point in the array. 

* DoClosepath -— This procedure is called at the end of 
every contour if the QuickDraw GX shape is closed 
(has the gxClosedFrameFill shape fill attribute). 
Closing a contour implies connecting the last point in 
the contour (whatever the current point is when this 
function is called) with the first point in the contour 
(the point passed into the DoMoveto function). 

The code shown in Listing 1 is a sample application 
(SamplePathWalker.c) that converts a piece of text to a 
path and then uses the Shape Walker library to read the 


Listing 1* Sample application using the ShapeWalker library 

// The following structure is used to maintain a state while walking a shape, 
typedef struct { 

gxFoint currentFoint; // current point 

gxFoint firstPoint; // first point in contour 

} TestWalkRec; 

fdefine fix2float(x) ((double)x / 65536.0) 

Boolean TestMovetofgxPoint *p, TestWalkRec* pWalk); 

Boolean TestMoveto{gxPoint *p, TestWalkRec* pWalk) 

{ 

printf("Begin new contour; %f, %f\r\n", fix2float(p->x), fix2float(p->y)); 

pWalk->currentPoint.x - p->x; 

pWalk->currentPoint.y = p->y; 

pWalk->firstPoint,x = p->x; 

pWalk->firstPoint.y = p->y; 

return (false); 

} 

Boolean TestLineto(gxPoint *p, TestWalkRec* pWalk); 

Boolean TestLineto(gxPoint *p, TestWalkRec* pWalk) 

< 

printf("Line from %f, %f to %f f lf\r\n" r fix2float(pWalk->currentPoint.x), 

fix2float(pWalk->currentPoint.y), fix2float(p->x), fix2float(p->y)); 
pWalk->currentPoint.x = p->x; 
pWalk->currentPoint.y = p->y; 
return (false); 

> 

(continued on nex/ page} 
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Listing 1* Sample application using the ShapeWalker library (continued) 

Boolean TestCurveto(gxPoint p[3], TestWalkRec* pWalk); 

Boolean TestCurveto(gxPoint p[3], TestWalkBec* pWalk) 

{ 

printf("Curve from %f, %f through %f, %f, to %f, %f\r\n", fix2float(p[0]*x), fix2floatfpf0].y), 
fix2float(p[1],x), fix2float(p[1],y), fix2float(p[2].x), fix2float(p[2].y)); 
pWalk->currentPoint•X = p [ 2 ]. x; 
pWalk->currentPoint.y = p[2].y; 
return (false); 

} 


Boolean TestClosepath(TestWalkRec* pWalk); 
Boolean TestClosepath(TestWalkRec* pWalk) 

{ 

printf ("Closing the contour\r\n\rW); 
pWalk->currentPoint*x = pWalk->firstPoint.x; 
pWalk->currentPoint.y - pWalk->firstPoint.y; 
return (false); 

} 


main() 

{ 

gxShape 

gxFoint 

TestWalkRec 

Boolean 


theShape; 

location = {ff(100) r ff(lQG)}; 

walker; 

result; 


theShape = GXNewText(5, "Hello", &location); 

GXSetShapeTextSize(theShape, f f(5 0)); 

GX S et S h apeType(t he Shape, gxP a t hType); 

GXSetShapeFill(theShape, gxClosedFraitieFill); 

result = ShapeWalker(theShape, TestMoveto, TestLineto, TestCurveto, TestClosepath, swalker); 
GXDisposeShape(theShape); 


points from the result. In this example the callback 
procedures are used only to print out the points in the 
segments, but of course they can be used to do a lot of 
other things as well, 

WALKING THE PATH 

The files PathWalking.h and Path Walking, c are all that 
are required to use the ShapeWalker library' in your 
application (for the sake of brevity, PathWalking.c isn’t 
shown in this column). This library should make it easy 
for your application to process QuickDraw GX path 
objects. For completeness, the library will also process 


curve objects, line objects, rectangle objects, and polygon 
objects in a similar manner. All other shape types will 
result in the posting of tire illegal_type_for_shape” 
graphics error. (Graphics errors can be polled with the 
GXGetGraph icsErr or function.) 

The ShapeWalker library' is actually based on the same 
code used by QuickDraw GX in its built-in GX-to- 
PostScript translator for printing. The library’s 
versatility means that its uses in your application are 
limited only by your imagination, so get creative and 
try it out! 


Thunks to Dave Hersey, ingrid Kelly, and Dave Polaschek for 
reviewing this column, * 
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Macintosh 

Q&A 


Q 

A 


What books and articles would you recommend that provide strategies for debugging? 
Here's a list of resources that can help you with debugging on the Macintosh: 


* How to Write Macintosh Software by Scott Knaster and Keith Roll in 
(Addison-Wesley, 1992). This hook describes how to find all the hugs you 
wrote when you used memory manipulation in C. 

* Debugging Macintosh Software With Macs Bug, by Konstantin Gthmer and Jim 
Straus (Addison-Wesley, 1991), and MacsBug Reference and Debugging Guide 
by Apple Computer, Inc. (Addison-Wesley, 1990). These books don't 
describe the latest version of MacsBug; check the MacsBug 6.5.2 release 
notes for additional details. 


* “Macintosh Debugging: A Weird Journey Into the Belly of the Beast” by 
Bo3b Johnson and Fred Huxham, develop Issue 8, and “Macintosh Debugging: 
The Belly of the Beast Revisited” by Fred Huxham and Greg Marriott, 
develop Issue 13, 

* “Debugging on PowerPC” by Dave Falkenburg and Brian Topping, develop 
Issue 17. 


• “Balance of Power: MacsBug for PowerPC” by Da ve Evans and Jim 
Murphy, develop Issue 22. 

* “KON & BAKs Puzzle Page,” in every issue of develop since Issue 9. 


Q 


/ have a customer who's encountering a problem using my product. Can you suggest a 
way to use MacsBug to diagnose problems at a cusUmier site? 


Yes. Here, in a few easy steps, is a technique for using MacsBug to diagnose 

problems in the field: 

J. Install a clean copy of the latest MacsBug. 

2. Create a file using ResEdit (or Resorcerer, or whatever) containing an 
r mxbni resource {which contains MacsBug macro definitions) and install it 
into the MacsBug Preferences folder. 

3. In this 'mxbrn' resource, define the macro everytinie to call the stdlaginto 
macro as follows: 


stdloginto ’Send to the programmer’ 

This way, if MacsBug is ever invoked due to a program error, a log of what 
occurred will be automatically generated. The log, named “Send to the 
programmer,” will appear on the desktop. 

4. Have your customer send you the log file created by the above steps. 


See page 219 of the MacsBug Reference and Debugging Guide by Apple Computer, 
Inc. (Addison-Wesley, 1990) for details of the everytmte macro. For details of 
what the stdloginto macro does, look at the ’mxbm 1 resource named “log stuff 
in Macs Bug's resource fork. 


Q 


We're developing an application that uses Apple Guide. IPs working well on 680x0 
Macintosh computers but is presenting a problem on the Power Macintosh, because of 
Apple Guide Glue. If we impotr this library as “weak , ” the program rum but crashes 
when we call any Apple Guide routines. If we import “strong, ” the program simply 
refiises to run. What can we do? 
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Linking with the .xcoff file produces a reference to a shared library named 
AppIeGuideGlue. Unfortunately, the Apple Guide extension provides a library 
named AppleGuideGlueLib instead, so the reference isn’t resolved and the 
application fails to launch. 

The AppleGuideGlue.xcoff file has been changed to AppleGuideGlueLib.xcoff 
on the latest Mac OS SDK CD, You can use that one, or just rename the one 
you have before including it in your project. 

In MPW, you can rename the library in the link process. If you’re using Symantec 
C or C++ or Code Warrior, however, the name of the file has to be correct for 
the matching library to be found at run time. Note that CodeWarrior ignores 
the “.xcoff 5 suffix if it 5 s present in the filename, while Symantec must have the 
“.xcoff 5 suffix to properly include the file in the project 


Q 


My QuickDraw GXprinter driver has a f ptyp* of U A4 portrait” as the default paper 
type (via the isDefaultPaperType flag). But when a user chooses my driver from the 
Page Setup dialog, A4 is selected as the default paper type in the desktop printer, though 
my driver has no ptyp ' named A4. How can 1 set my own paper type (A4 portrait) as 
the default? 


The paper-matching code is working incorrecdy. QuickDraw GX internally 
adds the standard paper types (such as A4 and US Letter) to the options for 
your driver. The bug is that QuickDraw GX thinks ids finding a better fit for 
the current page dimensions than the assigned A4 portrait paper type. It then 
defaults to the internal A4 paper type. 


The only workaround at this rime is to remove the paper type that you’re 
incorrectly defaulting to. If you’re defaulting to a nonstandard paper type, such 
as Letterhead, Stationery, or Three-hole Punch, the best workaround is to remove 
that type from the Extensions folder. If you’re defaulting to another paper type, 
the easiest thing you can do is to open your driver with a resource editor and 
remove or edit the ptyp 1 resource for the paper type that’s incorrecdy matching. 
(Open the resource and yoifll see the paper type name embedded in the data.) 


Q 


Pm creating a QuickDraw GX page that contains a line of single-layer text shapes, with 
each word a different color The page displays correctly when ifs opened in ShnpleText 
but shows a hug when it's printed to a PostScript prin ter: each line prints with one color 
instead of each word being a different color Any ideas? 


A 


This is a bug that occurs only with single-layer text shapes that have a nil style 
in their face layer. There’s a workaround that should be used anytime you do a 
one-layer text face, except for italics — this workaround slows down italic drawing 
but speeds up all other cases. 


Create a “generic” style object (with GXNewStyle) to replace the nil style. Set 
the text size to LO (important) and the pen to 0 in die style. The other fields are 
irrelevant to this fix. Set your text face’s style to this “generic” style and the 
problem will disappear. 


Q 


Pm having a problem ; apparent at very small font sizes (6 points and below), with the 
output quality of some fonts that emerge from a QuickDraw GX vector driver My 
application uses gxLayoutsfor text display and editing, if I mate my output using 
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GXDnnv Shape to render the layout shapes, the small characters begin to look very 
crude: character height varies by about 30% between some letters , and curved letter 
forms degenerate to rough polygons. What can I do to improve the quality? 


A 


Layouts (like all typographic shapes) have hints turned on by default. If the font 
you're using isn't hinted at small point sizes, using hints messes up the appearance 
of the text rather than helping it. Try using the layout shape and setting the 
gxNoMetricsGridText and gxNoContourGridText bits in the text attributes. 
The results at small sizes should be better. 


Q 


Pm writing an Open Transport client program, and Pm confused about haw to perform 
an orderly release when 1 receive the TjORDREL message. When I get the T_ORDREL 
message Pm supposed to call OTRwOrdetiyDiscmnect. The documentation for 
OTRcvOrderlyDisconnect says that I can then continue to send data but that I can't 
read data without getting an “out of state ” error (kOTOutStateErr). Is this comet? 


A 


Yes, it is. Your confusion is due more to the dynamics and subdeties of X/Open 
Transport Interface (XTI) programming than to Open Transport itself 


Let's examine an orderly disconnect situation. Assume that two nodes have an 
established TCP connection. Endpoint A has finished sending data and 
indicates closure by invoking an OTSndOrderly Disconnect call (this translates 
into sending an end-of-file signal — FIN — over the wire). Endpoint B receives 
a T_GRDREL message. If, however, B hasn't finished receiving the data, B 
must continue until it gets back kOTNoDataErr. At this point, B initiates an 
OTRcvOrderlyDisconnect (which acknowledges A's FIN). This is known as a 
“half-close"; B can still send data to A (which will still receive T_DATA events), 
but if A attempts to send to B, A will receive an u out of state” error. 


A, of course, should also continue accepting data until receiving kOTNoDataErr. 
A should then call OTRcvOrderlyDisconnect, thereby completing the other 
side of the link teardown. Both sides can then unbind. 


If however, either endpoint's network code is written such thatT_ORDREL and 
T_DATA events a re handled at different priorities (for instance, the T_ORDREL 
is handled at the notifier, but the T_DATA is deferred to SystemTask time), a 
race condition can occur. Your program must ensure that all data has been read 
before calling OTRcvOrderlyDisconnect. 

There’s also a subtlety of XTI programming that you should be aware of It's 
possible that OTSndOrderly Disconnect or OTRcvOrderlyDisconnect will 
return with a TLOOK error. This means that there's another event pending; 
your program must call OTLook to gather that event. 

According to the XTI specification, the OTSndOrderly Disconnect and 
OTRcvOrderlyDisconnect calls can fail because of a pending ^DISCONNECT 
event. XTI is trying to tell you that the connection to that endpoint broke. This 
can happen easily in our modern, wacky, asynchronous world of networks, and 
your program will have to call OTRcvDisconnect to acknowledge that your 
endpoint dropped. 


Q 


Pve implemented a server endpoint that hands off the connection to a hand-off endpoint 
After the server processes a connect request with the OTAccept call , the asynchronous 
handler for the hand-off endpoint is passed a T_DATA event . When the handier makes 
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the OTRco call , however, it returns error -3168 (kOTStateChangeErr). Can you 
explain this? 

A This problem occurs only when there’s a hand-off (secondary) endpoint involved* 
The way Open Transport is implemented, it’s possible for an asynchronous 
hand-off endpoint to receive a T_DATA event before the connect mechanism is 
completed* After accepting a connection, an asynchronous listener endpoint can 
expect to receive a T_ACCEPTCOMPLETE call. The “accepting” or hand-off 
endpoint can expect to receive the T_PASSCON event* 

It’s possible for the hand-off endpoint to receive the T_DATA event before 
receiving the T_ PAS SCON event, and this apparently is what’s happening to 
you. When this happens, set a flag to defer receiving the data until later. After 
the T_PASSCON event is received, check the flag and issue the GTRcv call if 
the flag is set* {Note that after deferring the handling of the T_DATA event, 
your handler won’t receive this event again until you process all of the data 
presently available.) 

Q IVhats the relationship between the classic AppleTalk “self-send* variable and the one 
in Opm Transport AppleTalk? 

A In version 1.1, Open Transport AppleTalk shares the self-send variable with 
classic AppleTalk, so if you set the variable with the classic PSetSelfSend call, 
the effects are seen by both AppleTalk and Open Transport clients. If you’re 
using Open Transport, you can change the variable with an OTIoctl call, as 
shown here: 

enum { 

kATalkFuliSelfSend = HIOC_CMD(MIOC_ATALK, 47} 

}; 


static OSStatus QTSet5elfSend(EndpointRef ep, Boolean enable self send) 

{ 

OSStatus result; 

result * OTIoctl{ep f kATalkFullSelfSend, (void *) enable_self_send); 
if (result > 0) 
result ^ 0; 
return result; 

> 

Note that like the PSetSelfSend call, the OTIoctl call returns the previous value 
of the self-send variable as either 0 (it was previously disabled) or 1 (it was 
previously enabled)* As in classic AppleTalk, it’s rarely appropriate to restore the 
value of self-send when you’re done, so the code above maps both results to 0 
(noErr), 

Here’s why the value shouldn’t be restored. The self-send value is a Boolean, 
not a counter. For example, imagine the following sequence: 

L Self-send starts out false* 

2* Client A sets self-send to true and is returned false as the previous value* 

3* Client B sets self-send to true and is returned true as the previous value. 

4. Client A quits, “restoring” self-send to false. 
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In the end, client B is left with self-send set to false, which is incorrect. 


For this reason, the standard practice is to set self-send if you need it and not 
attempt to restore it when finished. Because many clients follow this convention, 
it’s important that your program work even if self-send is true. 

Future versions of Open Transport will most likely have self-send always on for 
Open Transport native clients, and loop-back packets will be filtered out only 
for classic clients if PSetSelfSend wasn’t called. 


Q 


When I make a synchronous OTConnect call from a TCP client to a TCP server that's 
passively awaiting an incoming connection, I find that even before the sei-ver responds 
with the OTListen and OTAccept calls , the OTConnect call completes with no error. At 
this point , //1 examine the client endpoint state , l find that its in the T DATAXFER 
state . Can you explain this? 


A As mentioned in the XTI specification (available with the Open Transport 

release), “TCP does not allow the possibility of refusing a connection indication. 
Each connect indication causes the TCP transport provider to establish the 
connection. Therefore tJistenQ and t_accept() have a semantic which is slightly 
different than that for ISO providers.” Consequently, the server will accept the 
TCP connection request if the current n umber of connections allows it. The 
XTI specification states that “when the transport detects a T_LISTEN, TCP 
has already established the connection.” The client, whether in synchronous or 
asynchronous mode, will receive notice that the connection was established. For 
synchronous endpoints, TCP completes the three-way connection handshake. 
For asynchronous endpoints, the OTRcvConnect call must he made to complete 
the handshake. 


Q 


In my Open Transport TCP-based server application , / use a specific socket for receiving 
incoming connection requests. If I relaunch the server immediately after quitting , the 
initialization calls complete without error, but the server never receives any incoming 
connection requests. If I wait several minutes before relaunching the server, this problem 
doesn't occur It appears that there V some internal timeout for disconnected connections. 
Is their a solution to this problem so that the server can be relaunched without waiting 
for the timeout? 


A 


TCP has a two-minute timeout on a binding after a connection has closed 
before the same port can he bound to again. This prevents stale data from 
corrupting a new connection. For this reason, you see a delay before you can 
successfully bind to the port again. 


There’s a way around this, using the IP_,REUSEADDR option and the 
OTOptionManagement call. Set this option on all of your listening endpoints 
before you bind, and the problem should disappear. 


Note that even after yon use the 1P_REUSEADDR option, at most one endpoint 
that’s in a state less than connected (listening; unbound doesn’t count) may be 
bound to a given port. Any number of connected or closing endpoints may be 
so bound to other unique ports, however. 
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The following sample show^s how to set this option. The function takes two 
input parameters, the EndpointRef that you want to set the option for, and the 
state of the option that you want, typically true. The function returns a result of 







OS Status: if negative, it's the error returned from the OTOptionManagement 
call; if positive, it's the status field returned by OTOptionManagement (this 
means the call completed successfully but the status field had a value other than 
T_SUCCESS), If 0 (kOTNoError), then of course there was no error. 

♦Include <OpenTransport.h> // Open Transport files 

#inc1u d e <OpenTptInternet.h> 

/* input: reuseState (true: no delay, false; normal delay state) 
output: if result less than kOTNoError, it's the error returned by 
OTOptionManagement* Otherwise, the status value is returned as defined 
in OpenTransport.h: 

TSUCCESS = 0x020, return kOTNoError if success 
TFAILURE * 0x040, 

TFARTSUCCE5S » 0x100, 

TREADONLY » 0x200, 

T_NOT SUPPORT » 0x400 

*/ 


OSStatus DoNegotiateIPReuseAddrGption(EndpointRef ep, Boolean reuseState) 

{ 

UIntS buf[kOTFourByteOptionSize]; // Buffer for fourByte option 
TOption* opt? // Option ptr to make items 

// easier to access 

TOptMgmt reg; 

OSStatus err; 

Boolean isAsync * false; 


opt = (TOption*}buf; 
reg.opt.buf = buf; 
reg.opt.len - sizeof(buf); 
reg.opt.maxlen = sizeof(buf); 

reg.flags = T_NEGGTIATE; 
opt->level = INET_IP; 
opt->name = IP_RE U SEADDR; 
opt->len = kOTFourByteOptionSize; 

*(UInt32*)opt->value = reuseState; 

if (OTlsSynchronous(ep) == false) { 
isAsync = true; 

OTSetSynchronous(ep}; 

} 


It Set option ptr to buffer. 

// We're using req for the 
// return result also, 

// negotiate for option dealing 
// with an IP-level function* 


// Set the desired option 
// level, true or false. 

// Check if ep is synchronous. 
// Set flag if async. 

// Set endpoint to sync. 


err = OTOptionManagement(ep, Sreq, 6req); 

if (isAsync == true) // Restore ep state if necessary. 

OTSetAsynchronous(ep); 


N If no error, check the option status value, 
if (err == kOTNoError) { 

if (opt->status 1= T_SUCCESS) //If not T_J>UCCESS, return 

err = opt->status; // the status. 

> 

return err; 


Q 


I'm implementing a passive TCP connection. Can I hand off the connection to a different 
port address? 
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No, the hand-off connection endpoint must be bound to the same address as 
the endpoint that passed off the connection. This is an XTI requirement, as 
discussed in Appendix B of the XTI specification, Section B,3, 


I'd like my network client software to be able to abort an asynchronous OTConnect in 
progress — to allow a user, for example, to recover from an attempted connection to a 
nonexistent IP address. Fve been calling OTSndDiseonnect to abort it, but when I check 
the return code , I get a kOTOutStateErr error. What gives? 

Using an GTSndDiseonnect is the proper way to abort an OTConnect in 
progress. After a successful call to OTConnect, the endpoint state will transition 
from T_IDLE to T_OUTCON. Calling OTSndDiseonnect returns the 
endpoint state to TJDLE, 

You may be getting kOTOutvStateErr for one of the following reasons: 

* The original OTConnect failed. Determine this by checking the OTConnect 
result, 

* The connection broke and was asynchronously handled by your notifien In 
this case, your endpoint would no longer be in the T_OUTCON state 
before you do the disconnect, 

A good rule of thumb is always to confirm the endpoint state before doing the 
OTSndDiseonnect to ensure that the endpoint isn’t already disconnected. 


/ have a question regarding TJDATA event handling for m ultiple active endpoints. 

Let's say I have two endpoints open , endpoint 1 and endpoint Z Data anivesfor 
endpoint /, which then receives a T_DATA event. If data arrives for endpoint 2 before 
the data for endpoint 1 is read , it's my understanding that endpoint 2 won V get a 
T_DATA event until the data for endpoint I is read. Is that correct? In other words, does 
Open Transport queue multiple TJDATA events corresponding to multiple endpoints? 

XTI or Open Transport endpoints are handled independently of each other. 
Whatever events are pending on one endpoint have {for the mosi part) no effect 
on any other endpoints. 

.Assume that endpoint I gets notified of a T_DATA event. Following this, a 
separate T_DATA event is queued up for endpoint 2. As soon as the nodfier for 
endpoint 1 completes and returns to Open Transport, the notifier for endpoint 2 
will be invoked. This behavior isn’t contingent upon whether endpoint 1 
processed the event, although of course endpoint 1 won’t receive any more 
T_DATA events until its current TJDATA event is cleared. Keep in mind that 
waiting too long to process endpoint 1 ’s T_DATA event will result in the 
exhaustion of buffers in the lower protocol layers. 


Given an AppleTalk network and the node address of a Macintosh , how can I remotely 
retrieve the Network Name specified in the Sharing Setup control panel? 

The only universal way to determine a Macintosh’s “flagship" name is to target 
an NBP lookup of type “workstation" to that particular node. At first glance, it 
would seem that we could get the desired result by calling PConfirmName 
(since it allows us to direct the NBP LkUp to the specific node by using the 
confirmAddr field, whereas PLookupNanie would broadcast it to an entire 









zone)- The PCunfirmName call doesn’t return the NBP Tuple information to 
the application, however: under classic .AppleTalk, PConfirmName’s sole 
purpose is to confirm or deny the existence of a registered NBP name. This 
leaves you with several alternatives. 

Under classic AppleTalk, you have two options. The first option is to use the 
FLookupName call. This is a little complicated because PLookupName 
requires that you specify the “zone name” of the target node. You have to call 
GetZoneList and parse through the replies (illustrated in Inside Macintosh: 
Networking) page 4-7) to extract a list of zone names that correspond to your 
target’s network number. (Note that if you’re on an extended network, it’s 
possible for an AppleTalk zone to have a range of netw ork numbers.) Once you 
have a list of suspected network zones that the target is on, you can then direct 
a PLookupName to those zones and parse through the responses to find die 
one that matches your target’s node address. 

The second option under classic AppleTalk is to form the NBP LkUp packet 
yourself and send it via DDR You can open and register your own DDF listener 
by using the FOpenSkt call. You can then form your own NBP LkUp packet 
and transmit it to the target node’s NBP listener socket (socket 2) with the 
PWriteDDP call. The target will respond to you with an NBP LkUp-Reply, 
which will cause your DDF socket listener to be called. You can parse the reply 
there. 

Writing a DDF socket listener is tricky, but it’s illustrated in the Network 
Watch (DMZ) sample provided on this issue’s CD. Examine the doEcho 
function in the files dMZAT.c and SktListener.a. Writing a socket listener for 
the Power Macintosh can be challenging because of classic .AppleTalk’s 680x0 
roots. If you’re stuck with a classic AppleTalk system, however, this is the 
recommended approach. 

If your code is written to run under Open Transport, you’re in luck. You can 
specify the target address in the TLookupRequest data structure used by the 
OTLookupName function. Check out the DoSendLkUpReq function in 
DDPSampIe.ep, found on any Open Transport SDK CD. Since the programming 
model is so much simpler, you may w r ant to investigate the Open Transport 
approach. 


Q 


/ need to get the full pathname to a document in a callback where the only relevant piece 
of information I have is the Window Ptr for the window that contains the document. I 
can get the filename from the window title 7 hut 1 don't know the directory ID or volume 
reference number. Is there any way to obtain the dirlD and vRefNum from the 
Window Record? 


A 


No, there’s no way to extract the file system information you need from a 
WindowRecord. A WindowRecord includes only structural human interface 
information (which might include the filename as the window’s title) and has no 
intrinsic tie to any file on the disk. As you’ve implied, you must have the 
directory ID and volume reference number to extract a full pathname. Once 
you know the vRefNum and the parent dirlD, you’ll be able to use one of the 
full path routines in the sample code MoreFiles on this issue’s CD to construct a 
full pathname. 


If the file is open and you have the refNum for its access path, you can call 
PBGetFCBInfb to get the vRefNum and dirlD (and then use them to get the 
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pathname). For more information on PBGetFCBInfo, see Inside Macintosh: Files , 
pages 2-237 through 2-238. 


Q 


re// # that incorporates our own proprietary 3D technology. We'd like to be 

able to rake advantage of 3D acceleration hardware , if it's available on the user's 
system . JFZwf r/p yo// recommend we use? 


A Use the Rendering Acceleration Virtual Engine (RAVE) application development 
interface, which defines an abstract standardized hardware interface for 
applications to communicate with and control 3D hardware. If you adapt your 
game to draw to RAVE, it'll be compatible with any hardware 3D accelerators 
with RAVE-compatible drivers. RAVE is also a cross-platform specification, so 
code you write for the Macintosh will be easier to port to Windows 95 or 
Windows NT (if at some point in the future RAVE is implemented for Windows). 


Q 


We created a QuickDraw 3D application similar to the Texture Eyes demo distributed 
by Apple: it maps a moving image texture onto a spinning cube. The display quality of 
TextureEyes, however, is much better than ours. We're using large high-quality textures 
(480 .v 320% but the image mapped onto the cube is quite chunky even with a 3D 
accelerator card , and the animation seems to be slower and jerk ter. What's Texture Eyes 3 
secret? 


A No secrets: TextureEyes is a straightforward implementation of the texturing of 
QuickDraw 3D geometries. 'The problem is that the quality of your textures is 
actually coo high! 

QuickDraw 3D uses a trilinear MIP map algorithm to obtain the best possible 
quality texture mapping. To create an MIP map from an image requires creating 
subimages sized for every inverse power of 4 — that is, 1/4, 1/16, 1/64, and so 
on. The process of creating an MIP map for every texture takes time, and larger 
textures take longer. TextureEyes uses al28xl28 source for its movie and video 
textures. For more information on MIP maps, see Computer Graphics: Principles 
and Practice , hy Foley, VanDam, Feiner, and Hughes (Addison-Wesley, 1996). 


Q 

A 


My quartz watch is eetily accurate. Why? 

A quartz watch uses the vibrations of a quartz crystal as its time reference. The 
frequency of vibration in the crystal depends on three factors; voltage, pressure, 
and temperature. To keep the watch accurate, all three of these must be kept 
constant. 


The electronics in the watch provide a nice constant voltage, and the atmosphere 
provides a nice constant pressure. But what really ensures diat the watch is 
accurate is that it's worn on your wrist: the constant temperature of your body 
in contact with the watch ensures that the crystal operates at a constant 
temperature. 


These answers are supplied by the technical 
gurus in Apple's Developer Support Center. For 
more answers, see the Macintosh Technical G&As 
on this issue's CD or on the World Wide Web at 


h tip: //d e vj nfo, o pp le. co m/tec h qo/Ma i n. h tm I, 
(Older G&As can be found in the Macintosh 
Q&A Technical Notes on the CD.)* 


no develop Issuo 27 September W96 









DAVE JOHNSON 


THE VETERAN 
NEOPHYTE 

Your Friend the 
Drill Sergeant 


There are a ton of different ways to learn to shoot pool. 
You can just bash the balls around, trying to pocket them, 
and eventually you’ll get better at it. You can play games 
with other people, which increases the motivation 
somewhat, and probably learn a little faster. (Some 
people claim you should always play for money, because 
it makes it matter so much more.) But one of the most 
powerful ways to practice pool is plain old drill: setting 
up the same situation over and over, trying to make the 
shot a little better, a little more accurate, every time. 
Concentrated, repetitive drill is incredibly helpful in 
the early stages of learning the game, but it doesn’t stop 
there. Drill remains a useful practice method virtually 
forever. Many experts who have been playing for 30 
years still do regular drills, and still benefit from them. 


useful for learning high-level problem-solving skills. 
Since experienced programmers spend most of their 
time on problem solving and very little on mechanics, 
drill just isn’t an effective tool for getting better at 
programming once you’re past the early stages. 

Well, jeez, that was too easy. Isn’t there more to it than 
that? Surely there must be deep and profound differences 
between learning to shoot pool and learning to program, 
since the tasks themselves are so completely different. 
Programming is like — well, you know what it’s like, or 
you wouldn’t be reading drcelop. It’s mostly abstract and 
logical, and most of the real action takes place deep in 
your head or deep in the machine, far from the real 
world. Shooting pool is something else altogether. It’s 
unabashedly physical, it often defies logic, and the action 
takes place where everyone can see it, on a huge table 
made of wood and slate and rubber and cloth. 

I started playing pool fairly seriously several months ago, 
and I’m still embarrassingly terrible at it. In my typical 
overenthusiastic, obsessive-compulsive fashion, I dove 
in with both feet: I researched pool at the library, bought 
and read pool books, studied pool videotapes, cruised 
the Net for pool stuff, and jabbered about pool to anyone 
who came w'ithin earshot. The result was perhaps 
predictable. In no time, my knowledge of pool theory 
completely outstripped my ability to put it into practice. 
So although I could often see what to do in a certain 
situation, I couldn’t actually do it. All bark, no bite. 


But this stands in sharp contrast to programming, 
another skill I like to exercise (and analyze). Drill can 
be useful for programming neophytes, for learning 
such things as typing and the syntax of the language. 

But no experienced programmers I know engage in 
regular drill. The thought is actually ludicrous. What 
would you do? Write the same loop over and over, trying 
to do it a little faster or more accurately each time? 
Create a Hello World program from scratch 100 times 
in a row so that it becomes automatic? I don’t think so. 

So w r hat’s the difference between learning programming 
and learning pool? Why does drill have lasting value 
for one but not the other? 

A worthy question, I thought to myself. It’s deep 
enough that the answer should take a while to find, 
and interesting enough that the journey will keep my 
attention. So I girded myself for a long and arduous 
quest, set off smartly to find the answer, and stumbled 
over it immediately: drill is useful for learning mechanics 
— like high-precision muscular tasks — but it isn’t very 


To rectify this situation I started doing the only thing 
that would help: practicing doggedly. I took a lesson 
from a good instructor, and started hanging out at the 
pool hall as much as possible, putting in the practice 
time. Of course I was hoping that I’d suddenly make 
remarkable improvements in my game. But remarkable 
improvement is tough to come by in pool. 

At first glance pool seems like it should be very 
straightforward. You have nearly perfect spheres 
undergoing nearly perfecdy elastic collisions, so the 
paths of the balls should be nearly perfectly predictable, 
right? Wrong. Like most things that take place in the 
real world (as opposed to inside a computer), there’s a 
whole seething world of subtleties and nonlinearities 
and complexities just beneath the surface. The actual 
grungy details — the drag of the cloth, the spin of the 
balls, the fleeting grip they have on each other when 
they collide — all affect the paths of the balls profoundly, 
and are so complex and intertwined that people argue 
endlessly about what’s really going on. Superstitions, 
theories, rough approximations, and empirical formulas 
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abound. And all this complexity is set in motion in one 
tiny instant, by the impact of a chalked leather cue tip 
on a smooth plastic ball for a few milliseconds. If you 
ever needed an example of something with a sensitive 
dependence on initial conditions, this is a doozy. 

Because of its complexity and sensitivity, progress in 
pool is slow no matter how you approach it. Playing pool 
is one of those things you can do all your life and keep 
getting better at, like playing a musical instrument. And 
like learning an instrument, just playing is lots of fun, 
and can be fine practice. But concentrated drill on the 
basics, especially for a beginner like me, helps in a way 
no other kind of practice can. When I started regularly 
doing drills, the effect on my game was immediate and 
tangible (if not as remarkable as I might have liked). 

Good drill in pool involves intentional, conscious 
moving of your muscles the same way over and over, 
paying attention to the details of arm position, follow- 
through, rhythm, aim, and so on. You’re trying to 
consciously train your muscles to learn the motions, 
so that those motions can be performed unconsciously 
later. To use a handy computing metaphor {always a 
good idea when talking to programmers), drill is like 
programming an EPROM: it pushes something that 
initially requires conscious control (the software) dowm 
into the unconscious realm (the hardware). Drill helps 
you deliberately “wear grooves” in your brain. 

But that kind of “hardware” programming happens 
with any learning experience; it’s not unique to drill In 
fact, that’s what learning is. Drill is just one kind of 
focused, repetitive practice that helps you learn certain 
things faster. All learning involves pushing stuff “down 
into the hardware.” (And I mean that literally: scientists 
are starting to identify the physical changes that happen 
in brains when animals learn.) To muddle my metaphors 
a little, learning is like climbing an endless terraced hill, 
where what you learn becomes the ground you stand on 
to reach the next level. Details that once required your 
full attention get rucked down into the unconscious 
realm and are hidden, in the same way that the details 
of your code get tucked down into subroutines and are 
forgotten. The point is this: once you learn anything, 
you can climb up on top of it, and other things that 
were unreachable before are brought within your grasp. 

In my zeal to uncover the differences between learning 
pool and learning programming, I failed to notice the 
most remarkable thing of all: their similarity. The two 
goals couldn’t be more different. Programming is the 
crafting of precision machinery in a tightly controlled 


environment; pool is poking a ball with a stick (albeit in 
precise and skillful ways). Yet learning the two skills — 
for that matter, learning anything — is the same process. 
In fact, the more examples of learning I looked at, 
trying to categorize and separate them, the more the 
differences faded and the similarities came into focus. 

In every case, learning is the same kind of journey. We 
climb that tiered structure, that terraced hill, standing 
on what we’ve learned before so that we can reach the 
new stuff. We slowly convert tasks that initially require 
our full attention into automatic, mechanical ones, and 
that conversion to mechanics is what allows us to turn 
our attention to more meaningful, higher-level tasks. 

Attention seems to be the limiting factor here — we 
don’t have much of it. Reaching once again for the low- 
hanging fruit on the computational metaphor tree, 
attention is like a single-threaded program with a tiny 
stack: we can only pay attention to a small handful of 
things at a time. The funny thing is that our brains 
aren’t single threaded at all. Far from it! They are 
unbelievably prodigious and capacious things, and they 
actually are handling all the details, all the way down. 
We just aren’t aware of it. And believe me, that’s a good 
thing. 

Without some way to convert conscious activities into 
unconscious ones, to push the de tails down out of sight 
— to program ourselves — we’d never get anywhere. Our 
meager helping of attention would be used up in no 
time. It we had to struggle with typing and syntax on 
every line of code we wrote, we’d never get the program 
written. It we had to consciously move each and every 
muscle all the time, we actually wouldn't be able to walk 
and chew' gum at the same time — plain old standing 
around would probably he out of the question, much 
less hitting the cue ball with a little right English to 
sink the eleven ball and go two rails down table to get 
position on the thirteen. Lucky for us, the ability to 
program ourselves is built in. With a litde desire and 
disciplined practice, we can do truly amazing things. 

And oh, I do want to sink that thirteen ball. I really, 
really do... 


RECOMMENDED READING 

* Byrne's Standard Book of Pool and Billiards by 
Robert Byrne (Harcourt Brace, 1987). 


Thant s to Lorraine Anderson, Jeff Barbose, Brian Hamlin, Bo3b Dave wekosnes feedback on his musings, so please let him 

Johnson, and Ned van Alstyne for their review comments.* know what you think.* 
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Q 

A 


How can I opeti an application so that it displays a particular data item? 

If the target application supports Find, you can do that as long as three things 
are true: 

* You know the application symbol. 

* You know the application soup name and data format. 

* The application supports the ShowFoundltem message. 


If all of these are true, you can send the application the ShowFoundltem message 
with the appropriate arguments. Check the Newton Prognmrmers Guide for the 
arguments to ShowFoundltem. Be aware that not every application takes a soup 
entry as one of the arguments. That’s why you need to know the application’s 
data format. You can check whether the application supports the ShowFoundltem 
message with the following code: 


local theApp := GetRoot().(kAppSymbol}; 
if theApp AND theApp.ShowFoundltem exists then 

// application installed and supports the message 


Q 


We have an application for a Newton device that communicates with the desktop. Because 
of the structure of our data, we J d like to he able to request a particular NewtonScript 
object . We thought of sending the reference or address of the NewtonScript object to the 
desktop and using that as the identifier, but we could find no way to do this. Are we 
missing something? 


A 


Unfortunately {or fortunately, depending on your point of view), Newton 2.0 
OS doesn’t provide a w r ay to get the memory address of an object. Actually, since 
Newton Script can relocate objects at will, providing an address would not be a 
good idea. There’s an alternate approach: you can maintain an array of the 
objects you want to export. The array index can he used in much the same way 
as the address. As an example, in the code below, the memory “address” for 
object2 would be 1. In other words, myObjectArrayfl] w ould give you object2. 


objectl := "foo" j 

objects : = {can: 'aid, see: "an", a: "...yep")? 
object3 : = [1,2,3]; 

myObjectArray [objectl, object2, objectB]; 


If you need to indicate diat an object has already been transferred ro the desktop, 
you can simply replace the object at the relevant array index with NIL, 


Q 


Pm designing my data structures. I figure I could use either tu'o cursors onto tivo 
different soups or two cursors onto the same soup , Winch is the more efficient solution? 


A 


You can measure efficiency in two relevant ways: by time or by memory usage 
(or both). The time to create the two cursors will be the same regardless of the 
number of soups, but more heap space will be required for two soups. With two 
soups, it may take less time to find items that exist in just one soup than when 


The llama is the unofficial mascot of the 
Developer Technical Support group in Apple's 
Newton Systems Group. Send your Newton- 


related questions to drjlama@newton,apple.eom_ 
The first time we use a question from you, well 
send you a T-shirt. # 
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searching a larger, combined soup. However, with two soups you won’t get as 
much benefit from the operating system's caching of die entries; there’s more 
overhead information to swap in and out of the heap, which increases the time 
required to get data. 

The real answer is to test it with your actual data and see. Overall, two cursors 
on one soup sounds like the more efficient way to go. Your question implies that 
you’re going to have two completely different sets of data. You can do this in 
one soup by using indexes, because entries with either no indexed slot or NIL in 
an indexed slot won’t participate in that index. That is, when you create a cursor 
that uses that index, entries with NIL values will be ignored by that cursor. 

Something diat might occur to you is using tags to implement the two different 
sets of data (that is, each set would have a unique tag value), but this doesn’t 
work as well as using an index. With an index, you can navigate to an entry in 
G(log n) time, where n is the number of entries that are in that index. In other 
words, the time taken to navigate to a particular entry will he directly related to 
the log of the total number of entries. If your query includes a beginKey/endKey 
or startExcIKey/endExclKey subrange, the system finds that subrange very 
quickly. It can then quickly step through entries in between. 

7'he operating system gets the set of tags for an entry efficiently, but it has to 
know which entries to get the tags for first. So with no other way to narrow the 
search, it will check all the entries, assuming you aren’t using an index. Getting 
the tags is actually very efficient, but indexes work better for subranging. 


Q 


Fm tiying to compile a program that works with both Newton Lx and Newton 2.0 OS 
devices; however, it won V compile, Newton Toolkit complains that 1 have a had magic 
pointer .; but l kmrw that the value is defined in the Message Pad platform file. The 
offending code is as follows: 


local theCountries ;= 

call kGetUserConf igFunc with ( 1 contmonCcnmtries); 
if ClassOf(ROM_Countries) = ‘frame then 
if on a 1 ,x unit 

labelCorranands := foreaeh item in theCountries collect 
ROM_Countries.(item).name? 

else 


This would give a nice pop-up menu of countries on a Lx unit. Why doesn't it work? 

A This is a subtle problem. In Newton Toolkit 1,5 and later there are certain 
functions called emstmtfunctions that will evaluate at compile time when their 
arguments are constant. The most common ones are GetLayout, which will 
return a reference to another Newton Toolkit layout, and LocObj. The ClassOf 
function is another one of these. 

At compile time, a magic pointer is considered a constant value. That means 
that the ClassOf call in your conditional is executing at compile time. Of course, 
there’s no Newton device around at compile time, so Newton Toolkit is unable 
to dereference the magic pointer. Hence the error. 
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One workaround is to set a local to the value of the magic pointer and use that 
local in your conditional. This works because the value of the argument to 
ClassOf is no longer a constant, so it will not be called at compile time. 









local mpCountries := BOM_Countries; 
if ClassOf(mpCountries) = “frame then 


Q 


My communications program has a number of standard packets of information, Vm 
trying to set up constants for each of these standard packets. However, for the packet 


constant kHaltAndCatchFireMessage "\ulG2cff 1003 11 ; 


Mew ton Toolkit complains that there's an "odd number of digits between \u \\ M / count 
ten, which looks even to me. Does Newton Toolkit need a remedial math course? 

Actually, Newton Toolkit is doing fine in math, but it should say “bytes” instead 
of “digits,” There are ten hex digits in your string, but there are two hex digits 
per byte, so your string is five bytes long. Since Unicode is a double-byte 
representation, there are four hex digits per Unicode character. You have ten 
hex digits, or two and a half Unicode characters, which is an invalid Unicode 
string. 

You can cither add two more hex digits to your string or use the Make Binary 
and Stuff... functions. If you’re dealing with data that’s not strings, the latter 
method is the best one for compatibility. It’s also likely to keep you saner 


Q 


Fm trying to dial the following number using a Newton Fax Modem with my 
MemgePad 130: M 18Q05SH234 WW% l»»m^55-1234» > J23-456-789M23 i „ ", 

/ get an error -16013 in my communications code whenever I do this . / need to use the 
long string because it contains a calling card number. My modem dials correctly and the 
modem at the other end picks up. / even hear the chirping whistle of exchanging hits . 
But suddenly things just stop and the error occurs , Any clues? 


A Yes, First star on the right, then straight on till morning. But that’s a different 
story. In answer to your question, it looks as though you’re timing out on the 
connection attempt. Modems have a set amount of time to establish a connection, 
and the commas are reducing the time they have. Each of the commas will insert 
a delay into the dialing. For most modems, the time for each comma is controlled 
by register S08 and usually defaults to 2 seconds. You have 19 commas, so that’s 
38 seconds, which leaves very little time for the modems to sync up (the chirping 
whisde exchange you’re hearing). 


The solution is to increase the timeout of the modem to a more reasonable 
value. When you’re thinking about the timeout, remember that each digit will 
take around 95 milliseconds to dial. There will also be a line connection time of 
about 2 seconds, a ring time of a few seconds, and the final sync-up or negotiation 
time of 2 to 15 seconds. You should increase your timeout values to at least 60 
seconds. If that doesn’t work, add 30-second increments. You can do a binary 
search to narrow it down to an optimal value. 


To set the timeout for the modem, use 60 for the waitForCarrier (sixth) argument 
of the kCMOModemDialing option. The following bit of code will do this; 


// make a modem option data structure based on user preferences 
local option := MakeModemOption(); 

II modify the timeout value 
option.data,arglist[6J := 60; 

// set that option in your endpoint 
ep:Option(option); 
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Q 

A 


Hmv can I tell whether a tap is the first of a double tap f 

Unfortunately, the RUxM (Read User Mind) ASIC didn’t get completed in time 
for Newton 2.0 OS, so we were unable to implement the IsFirstTap global 
function. We also looked at a wireless link to one of the 900-number pay-by- 
the-minute psychic lines but couldn’t figure out how to bill the user. 


But seriously, you can’t tell. The best you can do is to hold off processing the 
first tap for some amount of time. If you receive another tap in that time, it’s a 
double tap. The drawback is that if it isn’t a double tap, you’ve lost the unit 
parameter from the first tap* since you can’t save this parameter. The other 
option is to follow a user interface guideline: Make the second tap an extension 
of the functionality that happens with the first tap. Then there’s no need to 
handle the first tap in a special way. 


Q 


We have a problem with union soups. We have an application that creates soups and 
transfers them to a PC. The soups can get sent down to a different MessagePad. If the 
user inserts a storage card and selects it as the default store , we can Y successfully add an 
item to the soup. Our code does a Get Union So up A /ways, then tries to add an entry 
using AddToDefimltStoreXmit. The Newton throws an exception that tells us there V 
no soupDef Were sure that the soup doesn't exist on the store , but we thought that 
Get UnionSoupAhvays creates the soup if you hy to add something. One thing we 
thought of was to use RegUnionSoup, hit our transfer application doesn't know what 
the soupDef is. Is there a way to copy a soupDef from one store to another or to get the 
soupDef from an existing soup? 


A 


Well, first you need some good onions, then some stale French bread, Gruyere 
cheese...oh, sorry, I thought you said “onion soup.” 


For a union soup to work properly in Newton 2.0 OS, a soupDef must exist in at 
least one of two places: It can be registered with the OS via RegUnionSoup, or 
it can exist within a soup that’s on a mounted store. GetUnionSoup Always should 
fail if there’s no soupDef present. However, in the current release of the Newton 
2.0 OS ROMs it doesn’t. This means the problem is deferred until you first try 
to add an entry, which is when the OS tries to create the soup but can’t find the 
soupDef. That’s why you get the error on the call to AddToDefaultStoreXmit. 
Of course, this doesn’t help you, but there are a few options: 

* Make sure that a soupDef is registered, via RegUnionSoup. 

* Make sure that an actual soup exists on some store and that that soup contains 
an embedded soupDef. The soup doesn’t actually have to have any entries. 
Yon can use the CreateSoupFromSoupDef function or the GetMember soup 
message to do this. For example: 

RegUnionSoup (JcMySoupDef) s GetMember (GetStores () [ 0 ]); 

* Don’t use union soups; instead, have your download application just send 
the store either the CreateSoupXmit or the GetSoup message. 

* Write some smart code that checks to see if a soup with the same name 
exists on any store and duplicate that soup on the new default store. If you 
use Getlndexes/CreateSoupXmit and GetAllInfo/SetAIlInfoXniit, you 
should be able to make a reasonably similar soup. 


116 devetop Issue 27 September 1996 


Unfortunately, there’s no supported way to directly access the soupDef of an 
existing soup. 





Q 


l have an application that performs some lengthy initializations in the install Script. / 
need a slip to come up and inform the user that this action is occurring , The problem is 
that the BuildContext slip I create at the beginning of the instaUScript doesn't show up 
when the instaUScript is running. How can l get a slip to come up in my mstallScript? 


I assume that you do something like create the slip, send the slip an Open 
message, and then do a tight loop with some initializations. If so, the system has 
probably opened your view, but your instaUScript is still executing. That means 
the system cannot refresh the display. 


One possible approach is to call Re fresh Views to force the system to update die 
display. However, if your progress indication ts dynamic, you’ll have to call 
Refresh Views each time you change die progress slip. A better approach is to 
use the DoProgress call, which provides a standard “Your Newton device is doing 
something” interface for the user. You may also want to do your initialization in 
a deferred action. 


Q 


Td like to add another item to the address picker pop-up list in my “To;," “Cr;,” and 
il Bcc: ” pickers that would allow the user to create an e-mail address without adding it to 
the Names soup . The user interface reasoning behind wanting to do this is to avoid 
cluttering the Names soup with addresses that are used only once. Tve successfully added 
an item to the picker and caught the pickActionScript for it. The pick item that l want 
to use to add this temporary name appears in the proto A ddress Picker pop - up list , Now 1 
want to bring up an editor and add my temporary hern . / tried the call 


GetDataDefs( 1 |nameRef,email|):New(tapInfo f self); 


from my proto A ddress Picker V pukAction Script, but I got an exception: Object {class: 
nameRef.email name: "E-Mailaddresses”, preferredRouting: [stringwmail]^ ...} is 
read-only. Why can V / create a new data object with this? 


A 


Usually answers to these questions are reasonably self-contained; this is an 
exception. Before you can understand this answer, you really need to read up on 
list pickers and data, or you’ll be tripped up by the subtle differences between 
name Refs and dataDefe, 


The transport system uses a structure called a nameRef for information on where 
to send things. Tt so happens chat nameRefs use the data definition registry as a 
repository. However, a nameRef is a different heasrie from a dataDef. To create 
a new empty nameRef structure, you can use the call 

GetDataDefs('|nameRef•email|);MakeNameRef{taplnfo, self); 

Then you can use some sort of floating editor to enter the values. I suggest using 
a protoFloatNGo that contains a newtFalseEntryVie w and then appropriate slot 
views for the fields of the nameRef that you want to edit. 


Thanks to jXopher Bell, Henry Cate, Bob Ebert, 
David Fedor, Ryan Robertson, Jim Schram, 
Maurice Sharp, and Bruce Thompson for these 


If you need more answers, check out 
http://devJnFo.appie.com/newton on the World 
Wide Web.* 


answers. 
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KON & BAL'S PUZZLE PAGE 


QuickTime Quandary 


See if you can solve this programming puzzle, presented in the form of 
a dialog between Konstantin Othmer (KON) and Bruce Leak (BAL). 
The dialog gives clues to help you. Keep guessing until you're done; your 
score is the number to the left of the clue that gave you the correct answer 
Even if you never run into the particular problems being solved here, 
you 'll learn some valuable debugging techniques that will help you solve 
your own programming conundrums. And you'll also learn interesting 
Macintosh trivia. 



KONSTANTIN OTHMER 
AND BRUCE LEAK 


KON So, BAL, it seems we need to increase our advertising budget to rope 
in more guest Puzzle Page authors. 

BAL People don’t realize the fame and fortune that comes with being part 
of the Puzzle Page. 1 heard that one person had a lot of good luck 
shortly after making her first Puzzle Page submission. 

KON I heard that another person who thought about submitting a column 
to the Puzzle Page, but then decided not to, lost some valuable files. 

BAL Enough chain letter tactics. Maybe if we write another column about 
QuickDraw or QuickTime, someone will be hungry enough for a 
change of pace to submi t his own Puzzle Page. 

KON I figure we should talk about the Internet and then take the Puzzle 

Page public! $10 to $12 a share sounds about right to me. Then we can 
have some serious writing bounties! 

BAL Maybe we’ll change die medium. Instead of printing it, we’ll deliver it 
over TV. 

KON OK, actually I do have a weird problem. It might be QuickTime- 

related. Pm trying to do some video digitizing, but every time I bring 


KONSTANTIN OTHMER AND BRUCE LEAK 

dropped off this press release in lieu of the usual 
biograph fed information: 

PALO ALTO, California, April 1, 1 996 — BalKon 
Heavy Industries today announced PuzzleMiH™, 
a next-generation, low-cost, networked virtu a i 
puzzle architecture for the World Wide Web, 
corporate intranets, infinity, and beyond. H Along 
with our industry-standard Puzzle Page column, 
we've set the agenda for digital puzzling info the 


next century" said BAL, BalKon's senior vice 
president for corporate restructuring. BalKon's 
executive vice proconsul for corporate misconduct 
KON will be acting as grist for the PuzzleMill 
until a sack of flour can be found to replace him 
KON let spill that the beta version of PuzzleMill 
can be downloaded free of charge from 
h ftp://www. a I way s. ba I kon. com "u nti I we 
achieve critical mass, at which point well charge 
as much as we want for it, darn it."* 
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up the Video Settings dialog to choose a compression method, my 
machine locks up. 

Locks up? How? Dead cursor, no MacsBug, the works? 

The cursor is still alive. I can even go into MacsBug and choose Exit to 
Shell and everything's fine. But I can't capture video since the dialog 
just hangs. 

What does the dialog look like when it hangs? Can you click in other 
applications? 

The basic structure is there. It draws the outline of the Choose CODEC 
pop-up menu, but there's no text. You can click all you want, but no 
context switch occurs. You're stuck. 

T've never heard of that before. Why does this stuff always happen to 
you, KON? 

Believe me, Fd love to know the answer to that puzzle! 

With all your problems, you should wTite a book on debugging. 

Anyway, back to my QuickTime nightmare. Any ideas? 

Clearly, that case has worked for millions of people for a long time. 

Tell me more. There's probably something funny about your machine. 

I have a Power Macintosh 8100/80. I had an 1IPV card but then traded 
Shannon for his AVcard. \ tried to buy an AV card, but it's really hard 
to get one. 

You always have weird hardware and other stuff. What version of the 
system are you running? This isn’t some beta card again, is it? 

I had version 7.1.2 originally but as soon as I started having problems 
with QuickTime I figured l ! d take the opportunity to “upgrade" to 
System 7.5. All my hardware is stock Apple stuff. I've written a lot of 
crazy programs, the results of many of which have appeared in these 
pages, but the hardware seems to be kosher. 

Which version of 7.5? 

1 started with plain 7,5. Then I heard about the fix release, so I 
upgraded to 7.5.1.1 put the project on hold for a while, and heard 
about a fix for the fix, so I installed 7.5.2, There was a fix-cubed 
release, so now I'm running 7.5,3 and it still happens. Maybe I should 
wait for 7,5.4? 

Come on, KON. Clearly the problem isn't related to a system release. 
You did a clean install, right? 

Last I heard, the magic incantation was to drag the Finder inside the 
Preferences folder, rename the System Folder, jog around your chair 
three times, and say a prayer 

Did you sacrifice a frog? 

Seriously the system install is fine. 

What version of QuickTime is it? 

QuickTime 2.L That was the latest version I could find. Movies play 
back OK — it's just this capture thing that’s giving me fits. 

I guess you’ve tried replacing QuickTime, Does this happen in other 
applications as well? 
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KON Fve tried three different applications. Every one has the exact same 
symptoms: it locks up when it brings up the Video Settings dialog. 

BAL On one level that makes sense. Applications just call QuickTime to put 
up that dialog. But what doesn’t make sense is that you have a clean 
system install, standard Apple hardware, and the latest QuickTime 
version,, and it hangs. That’s crazy. Any weird extensions or anything? 

KON Nope, Totally dean install. 

BAL Swap the hard drive. 

70 KON Still happens. 

BAL Swap the video card. 

60 KON 60 and falling fast. 

BAL The monitor? 

KON I ,et’s leave sense-line bugs for a later date. Now that you’ve swapped 
out the whole system except the motherboard, the TV repairman 
approach is over, 

BAL Fine. Give me MacsBug. I’ll break into the debugger when the system 
hangs and try to figure out what’s going on. 

50 KON It looks like you’re in the Font Manager routine RealFont, which is 
being called from a loop in QuickTime. Here’s what it looks like: 


Disassembling from IC5B562 
■CDEF 0064 QF6E' 


40 


+0I5B2 

01C5B562 

M0VEQ 

#$01,DO 

| 7001 

+015B4 

01C5B564 

MOVE■W 

D0,-(A7) 

| 3F00 

+015B6 

01C5B566 

TextFont ; Q019DOE4 

| A887 

+015B8 

01C5B5G8 

M0VEQ 

#$08,D6 

| 7C08 

+015BA 

01C5B56A 

BRA. 5 

"CDEF 0064 10E6 1 +015CA ; G1C5B57A 

| 600E 

+01 SBC 

01C5B5GC 

SUBQ.L 

#$2,A7 

1558F 

+015BE 

01C5B56E 

M0VEQ 

#$01,DO 

j 7001 

+015CO 

01C5B570 

MOVE.W 

DO,-(A7) 

j 3FOO 

+015C2 

0IC5B572 

ADDQ.W 

#$1,D6 

j 5246 

+015C4 

01C5B574 

MOVE.W 

D6,-(A7) 

j 3F06 

+015C6 

01C5B576 

*_RealFont ; 4Q8C2B2E 

|A902 

+015C8 

Q1C5B578 

MOVE.B 

(A7)+,D7 

11E1F 

+015CA 

01C5B57A 

TST.B 

D7 

j 4A07 

+Q15CC 

01C5B57C 

BEQ.S 

1 CDEF 0064 10E6 1 +01 SBC ; 01C5B56C 

| 67EE 

+015CE 

01C5B57E 

MOVE.W 

D6,-(A7) 

j 3F06 

+Q15DQ 

01C5B580 

_TextSize ; QGI9D18C 

A88A 

BAL 

Aha! It’s starring to sound a little like a QuickDraw bug to me! What 
kind of nastiness did you put in that code, KON? 

KON 

Not so quick, pal. RealFont is returning just fine. But the loop calling 
it doesn’t terminate. 

BAL 

Well, RealFont just tells you whether a particular font size exists. 



QuickTime calls RealFont to make sure that the drawing operation in 
the Video Settings dialog will look good: if the requested font size 
doesn’t exist, things will scale and look really ugly. In that case, 
QuickTime increments the font size and keeps looking. 


KON OK. 
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BAL These dialogs should be drawn with die system font. Is there some 
strange problem with your fonts that persists across system installs? 

I thought I told you to swap hard drives, 

30 KON l did a fresh install on a new hard drive and the problem continued. 

BAL Hmm. It sounds like the bug is that QuickTime is searching for a 

system font size that won't be scaled — that is, that's real. It probably 
expects it to be there. If ids not, QuickTime spins forever looking. 

KON OK, So why can’t it find it? 

BAL What font are you looking for? 

20 KON The font ID passed into RealFont is 1 (AppFont), which RealFont 
converts internally to the application font by reading the short at 
0x984 (ApFontlD). 


BAL What font is it? 

KON How do I figure that out? 

BAL Call GetFontName. We don’t even need to write a program to do this. 
You can hack the stack from MacsBug. First, go to some trap call so that 
you know the proper registers are saved and all of that. Subtract 6 from 
the stack. Put die address of where you want the name to end up at the 
old stack address, and the fontNum, 1, after that. Put the address of the 
GetFontName trap, OxASFF, at location 0, set the PC to 0, and trace. 


KON You should probably turn off Even Better BusError when doing this 
sort of thing. 


BAL Well, yes, that’s true. Or, alternatively, we could find a large free block 
somewhere and put the code there. Of course, we’d have to be sure 
the call doesn’t move memory, or our code might be written over — 
although for this single trap it doesn’t matter. Anyway, you get the idea. 


KON The work you’ll go through to keep from wriring any real code! Wait, 
Where do I get the memory for the name? 


BAL You have three choices: you could have subtracted another 255 bytes 
or so from the stack and just used that. Better yet is to use some of 
Macs Bug’s interna! buffer. When you use the dh command, MacsBug 
puts the hex data in a buffer and disassembles it. The address in the 
disassembly is the address of the MacsBug buffer. Finally, you could 
look for a free block with lots of space and use that. 


10 KON OK. The font name comes back 0* 

BAL If you trust that, it means there’s no font with that fontNum. So it 

makes sense that QuickTime would never find a RealFont at any size 
for that fontNum. 


KON So why didn’t the system install fix it? 

BAL The system font ID is stored in PRAM and is put in a low-memory 
global during startup. Apparendy the install process doesn’t touch 
PRAM, Zap your PRAM by holding Command-Option-Shift-P-R 
during startup — user friendly! 

KON OK. Now it works. 

BAL So the installer should clear PRAM when a new system is installed. It 
should keep your video card configuration and other settings, which 
really belong on the hard disk as well, but should clear stuff like the 
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default fonts since they may not exist, or they might he renumbered, in 
the new install, 

KON And QuickTime shouldn't spin in an endless loop expecting something 
to exist, 

BAL PRAM is a holdover from the 128K Macintosh, It was designed as a 
dosed system that might never have a hard drive. At that time there 
were only floppies, so it made a lot of sense to store system parameters 
with the machine rather than the media. But since then, no one has 
ever revisited whether PRAM is needed, 

KON The machine still has a ROM, for crying out loud! I guess it's too soon 
to give up those silly incantations of rebuilding the desktop and zapping 
PRAM, By the way, I understand the problem was worked around in 
QuickTime 2,5 by aborting the font search loop at a maximum point 
size of 56. 

BAL Nasty. 

KON Yeah, 


SCORING 

90-100 Yeah, sure. And you just had lunch with D. B. Cooper. 

70-85 Congratulations! You've just qualified to write the next Puzzle Page. 

40-60 Your spirit guides must be with you today, 

10-30 Care to join our poker game?* 

Thanks to Peter Hoddie, Josh Horwith, and Bo3b Johnson for reviewing this column, * 




How’re 

we doing? 

If you have questions, suggestions, or even gripes about develop, please don’t keep them to yourself. 

Drop us a line and let us know what you think. 


Send editorial suggestions or comments 

Send technical questions about develop 

to deveIop@apple.com or to; 

to: 

Caroline Rose 

Dave Johnson 

Apple Computer, Inc. 

Apple Computer, Inc. 

1 Infinite Loop 

1 Infinite Loop 

Cupertino, CA 95014 

Cupertino, CA 95014 

cr os e @a pp I e. com 

dkj@apple.com 

Fax; (408)974-9423 

CompuServe: 75300,715 

Fax: (408)974-9423 

Please direct all subscrip don-related queries to Apple Developer Catalog, RQ. Box 319, Buffalo, 

NY 14207-0319 or to order.adc@appleIink.appl 

e.com. You can also call 1-800-282-2732 in the 

U.S., 1-800-637-0029 in Canada, or (716)871-6555 elsewhere. 
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SRSpeakAndDrawText 14 


SRSpeechObject -9 
class hierarchy 7-8 
SRStartListening 8, 9, 16 
SRS top Listening 8 
SRWord 8, 9 

standard part kinds* See part lands 
Standard Type I/O utilities 
(Open Doc) 39 
static class objects (SOM), 

Open Doc and 69 
stdloginto macro (MacsBug), 
Macintosh Q & A 102 
’STR#' resources 

and the prts’ resource 61 
specifying 24-25 
Stuff.,,, Newton Q & A 115 

T 

T.ACCEF I ’COMPLETE (Open 
Transport), Macintosh Q & A 

105 

TApplication, Mac OS 8 assistants 
and 79 

TAssistant, Mac OS 8 assistants 
and 79 

TCP server connections 
Open Transport and 
(Macintosh Q & A) 

106-108 

passive (Macintosh Q & A) 

107-108 

T_DATA (Open Transport), 
Macintosh Q & A 104-105, 
108 

T_DISCONNECT (Open 
Transport), Macintosh Q & A 
104 

Technical Q & A 

Texture Eyes, Macintosh Q & A 

HO 

“The OpenDoc Road” (Lo), 
Facilitating Part Editor 
Unloading 69-71 
3D acceleration hardware, 
Macintosh Q & A 110 
“3D Geometry 101" 90-91 
3D geometry (QuickDraw 3D) 
90-91 

T_IDLE (Open Transport), 
Macintosh Q & A 108 
T_LISTEN (Open Transport), 
Macintosh Q & A 104, ! 06 
TLOOK error (Open Transport), 
Macintosh Q & A 104 
TLookupRequest (Open Transport), 
Macintosh Q & A 109 


T_ORDREL (Open Transport), 
Macintosh Q & A 104 
T_QUTCON (Open Transport), 
Macintosh Q & A 108 
T_PASSCGN (Open Transport), 
Macintosh Q &: A 105 
transformation matrix (3D 
geometry) 91 
transition vector (TVector) 

MaxApplZone and 82, 84 
Re lease Resource and 85-86 
traversing paths (QuickDraw GX) 
98-101 

two cursors (Newton Q Sc A) 

113-114 

u 

U D eskto p:: FetchTopR egul a r 
(PowerPlant) 30 
Unicode 

Newton Q & A 115 
OpenDoc and 38 
union soups (Newton Q & A) If 6 
universal file commands (File 
menu), speech recognition and 
27-29 

URL part kind (OpenDoc) 43 
“Using Apple Guide 2.1 with 
OpenDoc” (Commons) 53-68 

v 

vector (3 D geometry) 90 
rotation of 91 
translation of 91 
“Veteran Neophyte, The” 
(Johnson), Your Friend The 
Drill Sergeant 111-112 
Video Settings dialog (QuickTime), 
KON&BAL puzzle 119-122 
vRefNunt (Macintosh Q & A) 
109-110 

w 

window coaches (Apple Guide 2.1) 

63 

WindowRecord, file system 

information (Macintosh Q & A) 

109 

“Working With OpenDoc Part 
Kinds” (C^elik and Curbow) 

37-52 

X 

X/Open Transport Interface (XTI), 
Macintosh Q & A 104, 106, 108 


128 develop Issue 2 7 September 1V96 










RESOURCES 


Apple provides a wealth of information , 
products, and services to assist developers. 
The Apple Developer Catalog and Apple 
Developer University are open to anyone 
who wants access to development tools 
and instruction. Additional information 
and services are available through 
Apple's Developer Programs. 


Apple Developer Catalog To order o 
product or receive a catalog, calM -800- 
282-2732 in the US., 1-800637-0029 in 
Canada, (716)871-6555 internationally, or 
(71 6)871-65 1 1 For Fax. You can also send 
e-mail to order.adc@applelink.opple.com, 
or write Apple Deveioper Catalog , P.O. Box 
319, Buffalo, NY 14207-0319. The Apple 
Developer Catalog Is also on the Web at 
http: //www. devca ta I og. a p p le. ca m. 


The Apple Developer Catalog 

offers worldwide access to 
development tools, resources, 
training products, and information 
for anyone interested in developing 
applications on Apple platforms* 
This complimentary catalog features 
hundreds of Apple and third-party 
development products and offers 
convenient payment and shipping 
options, including site licensing. 

Apple Developer University 

(DU) provides courses to get you 
started programming on Apple 
platforms, as well as advanced, in- 
depth training on new technologies 
such as QuickTime VR, QuickDraw 
3D, GpenDoc, Apple Guide, and 
Newton, In addition to classroom 
training, self-paced courses are 
available through the Apple Developer 
Catalog , and free introductory 
tutorials are provided on the Web at 
http://dettmfo.apple.com/du.htmL 

The Macintosh Developer 
Program provides members with 
ongoing Macintosh-related technical 
information and services* It includes: 

* The monthly Apple Developer 
Mailing, which includes the 
Developer CD Series . 

* Macintosh technology seeding. 

* Programming-level technical 
support via e-maih Apple offers a 
number of options for varying 
levels of technical support* 


Apple Developer University Course 
descriptions and schedules can be Found at 
http://dev. info.apple.com/du.html on the 
Web. You can also call (408)974-4897, 
fox (408]974-0544, send e-mail to 
devuniv@applelink.apple.com, or write 
Developer University, Apple Computer, Inc., 
1 Infinite Loop, M/S 305-1TU, Cupertino, 
CA 95014. 


The Newton Developer Program 

provides ongoing Newton-related 
technical information and services* 

It includes: 

* The monthly Newton Developer 
Mailing. 

* The quarterly Newton Developer 
CD* 

* Newton development class 
discounts, 

* Programming-level technical 
support via e-mail. Apple offers a 
number of options for varying 
levels of technical support. 

The Apple Multimedia Program 

(AMP) provides resources to keep 
multimedia developers up-to-date 
on Apple’s offerings for authoring 
and playback* It includes: 

* The quarterly Apple Multimedia 
Information Mailing. 

* Access to a special members-only 
area on the AMP Web site 
(http://www.amp.apple.com). 

* Invitations to special events and 
participation in Apple events such 
as trade shows. 

* Seeding opportunities* 

* The Interactive Music Track, an 
extension of the AMP designed 
specifically for musicians, music 
industry members, and interactive 
music developers. 


Apple Developer Programs These 
programs vary on a counfry-by-country basis, 
Tor mare information on any of Apple's 
deveioper support programs worldwide, call 
(408)9744897, fax (408)974-7683, send 
e-matf to devsupporl@applefi nk.apple.com, 
or write Developer Support, Apple Computer, 
Inc,, I Infinite Loop, M/5 303-2T, Cupertino, 
CA 95014. 
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